> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an Earnings Preview

> Retrieve and preserve one issuer's earnings-preview bundle for a reviewable research brief.

Use this workflow to save one issuer's returned earnings-preview bundle before
anyone writes a research brief. The bundle is research input, not an earnings
forecast, completeness claim, or trade recommendation.

## Set up a clean environment

You need Python 3.9 or later, `requests`, and an SEC API key. This example uses NVIDIA.

```bash theme={null}
python -m venv .venv
source .venv/bin/activate
python -m pip install requests
export SECAPI_API_KEY="your_api_key"
```

## 1. Request and save the preview bundle

Create `earnings_preview.py`:

```python theme={null}
import json
import os
from pathlib import Path

import requests

ticker = "NVDA"
response = requests.get(
    "https://api.secapi.ai/v1/intelligence/earnings-preview",
    headers={"x-api-key": os.environ["SECAPI_API_KEY"]},
    params={"ticker": ticker},
    timeout=30,
)
response.raise_for_status()
bundle = response.json()

Path("earnings-preview.json").write_text(json.dumps(bundle, indent=2))
print(json.dumps({
    "object": bundle.get("object"),
    "requestId": bundle.get("requestId"),
    "traceparent": bundle.get("traceparent"),
}, indent=2))
```

Run `python earnings_preview.py`. It writes `earnings-preview.json` and prints the returned object identity and request metadata. A successful response is the bounded outcome for this step; bundle content can vary by issuer and selected filing context.

## 2. Make a review stub, not a synthetic forecast

Append this code after the request above:

```python theme={null}
lines = [
    f"# {ticker} earnings preview",
    f"Request ID: {bundle.get('requestId', 'not supplied')}",
    f"Trace: {bundle.get('traceparent', 'not supplied')}",
    "",
    "## Returned bundle",
    "See earnings-preview.json. Keep any source or trace context returned in the bundle with this review.",
    "",
    "## Reviewer notes",
    "- Read the returned supporting context before quoting a driver or risk.",
    "- Label any conclusion as analyst interpretation, not API output.",
]
Path("earnings-preview.md").write_text("\n".join(lines) + "\n")
```

This adds `earnings-preview.md` without assuming a stable internal shape for a
driver, risk, estimate, or citation. The expected result is the saved JSON plus
the review stub. Keep the JSON beside the note. When the bundle includes
supporting context, retain it unchanged; the source filing remains authoritative.

## Limits and failure modes

* The route requires `ticker` or `cik`. A failed retrieval is not evidence that an issuer has no earnings context.
* This filing-derived route does not provide consensus estimates. Keep any external estimate separately sourced and labeled.
* A driver or risk is not a forecast or materiality determination. Read the returned supporting context and the source before quoting it.
* Save each run with its request metadata. A later request can return a different bundle.

## Next step

Read the [earnings preview reference](/api-reference/intelligence/get-v1-intelligence-earnings-preview), then add a reviewer-approved source check before distributing the brief.