> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Brief Generation
> Learn how to run your own financial brief generation service with a pre-built Docker and the Bigdata API.
# What are Briefs in Bigdata?
Briefs are concise, automated reports generated by Bigdata's platform that help users stay informed about their watchlists and areas of interest. They are personalized market updates that deliver only the most relevant insights based on your watchlist, helping you stay informed without information overload. Unlike traditional newsfeeds or generic newsletters, they’re tailored to your interests and can be delivered when you prefered, whether that’s daily, weekly or any other frequency you choose.
# Deploy your own Briefs service
To support users building with Bigdata, we’ve released a pre-built Docker image that lets you run your own financial brief generation service. This service uses the Bigdata API to generate insights from the latest news and market data, serving as a foundational component you can easily integrate into your application to deliver timely updates on the companies that matter to you.
If you prefer to just receive scheduled briefs on your desired set of companies, you can use the [Bigdata.com Briefs feature](https://app.bigdata.com/brief) on our app.
## Setup
Some pre-requisites are required to run the service:
* A [Bigdata.com](https://bigdata.com) account that supports programmatic access.
* A Bigdata.com API key, which can be obtained from your account settings.
* For more information on how to get an API key, refer to the [Bigdata.com documentation](https://docs.bigdata.com/sdk-reference/introduction#api-key).
* An LLM and embeddings provider, currently the service supports OpenAI.
To build and run the Docker image, you need to have [Docker installed on your machine](https://docs.docker.com/get-started/get-docker/).
# Quickstart
To quickly get started, you have two options:
1. **Build and run locally:**
You need to build the docker image first and then run it:
```bash theme={null}
# Clone the repository and navigate to the folder
git clone git@github.com:Bigdata-com/bigdata-briefs.git
cd "bigdata-briefs"
# Build the docker image
docker build -t bigdata_briefs .
# Run the docker image
docker run -d \
--name bigdata_briefs \
-p 8000:8000 \
-e BIGDATA_API_KEY= \
-e OPENAI_API_KEY= \
bigdata_briefs
```
2. **Run directly from GitHub Container Registry:**
```bash theme={null}
docker run -d \
--name bigdata_briefs \
-p 8000:8000 \
-e BIGDATA_API_KEY= \
-e OPENAI_API_KEY= \
ghcr.io/bigdata-com/bigdata-briefs:latest
```
This will start the brief service locally on port 8000. You can then access the service `http://localhost:8000/` and the documentation for the API `http://localhost:8000/docs`.
For custom enterprise-ready solutions, please contact us at [support@bigdata.com](mailto:support@bigdata.com). If you are interested in using a different LLM provider—whether enterprise-grade or self-hosted solutions let us know by opening an issue on the [Bigdata.com GitHub repository](https://github.com/Bigdata-com/bigdata-briefs) or through our [support channels](https://docs.bigdata.com/support?utm_source=docs).
## Usage
The service provides a simple API to generate briefs for the companies in your watchlist. Once the service is running, you can access it on port 8000 by default.
You can find the API documentation at `http://localhost:8000/docs`, but the easiest way to get started is through a simple user interface built into the service at `http://localhost:8000/`.
To create a brief in a programmatic way, send a POST request to the `/briefs/create` endpoint with the following parameters:
* `entities`: The portfolio of entities you want to screen for exposure, either as a list of RavenPack entity IDs `["4A6F00", "D8442A"]` or a watchlist ID `"44118802-9104-4265-b97a-2e6d88d74893"`. Watchlists can be created programmatically using the [Bigdata.com SDK](https://docs.bigdata.com/getting-started/watchlist_management) or through the [Bigdata app](https://app.bigdata.com/watchlists)
* `report_start_date`: The start date of the report in ISO format (e.g., `2024-01-01`).
* `report_end_date`: The end date of the report in ISO format (e.g., `2024-01-31`).
* `novelty`: Optional, default is `true`. If set to `true`, the service will remember previously generated briefs and will only include novel information in following reports.
* `sources`: Optional, a list of data sources to include in the brief. If not provided, the service will use all available sources. Sources must be passed as a list of RavenPack entity IDs, e.g. `['9D69F1', 'B5235B']`.
* `topics`: Optional, a list of topics to focus on in the report. This is an advanced option, a set of handpicked topics focussing on financial relevance will be used if not provided. You can find the list of default topics at the [GitHub repository](https://github.com/Bigdata-com/bigdata-briefs/blob/master/bigdata_briefs/settings.py#L9-L37), please note the `{entity}` placeholder is required to improve the results of the search process.
The novelty feature operates using knowledge derived from previously generated briefs for each entity. Consequently, a new deployment with an empty database will have no prior context, and the novelty filter will not exclude any information until briefs have been created and stored.
To ensure novelty content, make sure your database persists across service restarts. If necessary, consider pre-populating it by generating initial briefs for your entities covering previous periods.
You can generate a brief by sending a POST request to the `/briefs/create` endpoint with the required parameters. Here are some examples:
#### Basic Example - Using a Watchlist ID
```bash theme={null}
curl -X 'POST' \
'http://127.0.0.1:8000/briefs/create' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"entities": "db8478c9-34db-4975-8e44-b1ff764098ac",
"report_start_date": "2025-09-23T15:00:00",
"report_end_date": "2025-09-30T15:00:00"
}'
```
#### Basic Example - Using Entity IDs
```bash theme={null}
curl -X 'POST' \
'http://127.0.0.1:8000/briefs/create' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"entities": ["D8442A"],
"report_start_date": "2025-10-27",
"report_end_date": "2025-11-03"
}'
```
#### Advanced Example - With Custom Topics and Configuration
```bash theme={null}
curl -X 'POST' \
'http://127.0.0.1:8000/briefs/create' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"entities": ["D8442A", "168A5D"],
"report_start_date": "2025-10-27",
"report_end_date": "2025-11-03",
"novelty": true,
"categories": ["news"],
"topics": [
"What notable changes in {entity}\u0027s financial performance metrics have been reported recently?",
"Has {entity} revised its financial or operational guidance for upcoming periods?",
"What significant strategic initiatives or business pivots has {entity} announced recently?"
],
"source_rank_boost": 10,
"freshness_boost": 8,
"disable_introduction": true
}'
```
**Additional Optional Parameters:**
* `source_rank_boost` (optional): Control how sources are prioritized (default: 10)
* `freshness_boost` (optional): Control freshness weighting for sources (default: 8)
* `disable_introduction` (optional): Skip the introduction section in the brief
* `categories` (optional): Filter report content by category. Available values: `expert_interviews`, `filings`, `my_files`, `news`, `podcasts`, `research`, `transcripts`
The response will include a `request_id`. You can check the status and get your brief with:
```bash theme={null}
curl -X GET \
'http://localhost:8000/briefs/status/' \
-H 'accept: application/json'
```
For more details on all available parameters, refer to the API documentation at `http://localhost:8000/docs`.
## Large-Scale Portfolio Briefs Generation
For generating briefs for large portfolios (hundreds or thousands of companies), see the [Large-Scale Portfolio Briefs Generation](https://github.com/Bigdata-com/bigdata-cookbook/tree/main/Briefs_Generation_Large_Scale) notebook in the bigdata-cookbook repository.
This notebook demonstrates how to:
* Process large numbers of companies in configurable batches
* Load company identifiers from CSV files
* Customize topics and research questions for different batches
* Monitor batch processing with status polling
* Export results to JSON and Excel formats
The notebook uses this briefs service API to generate briefs programmatically, making it ideal for portfolio managers and analysts who need to monitor many companies simultaneously. The service can handle large numbers of companies in a single request, and the notebook shows how to organize batch processing for scheduling across time zones or running concurrent service instances.
## Built on top the briefs service
Some functionality you may want to build on top of the briefs service are:
* **Scheduled briefs**: Automatically generate and send briefs to users on a regular basis.
* **Automatic watchlist management**: Automatically add or remove companies from the watchlist based on a [theme](https://docs.bigdata.com/use-cases/research-tools/screeners) or [risk exposure](https://docs.bigdata.com/use-cases/research-tools/risk-analyzer).