Build an Earnings Preview

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.

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:

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:

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, then add a reviewer-approved source check before distributing the brief.

Agent quickstart

Build an agent

Automate

Set up a clean environment

1. Request and save the preview bundle

2. Make a review stub, not a synthetic forecast

Limits and failure modes

Next step

​Set up a clean environment

​1. Request and save the preview bundle

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

​Limits and failure modes

​Next step

Set up a clean environment

1. Request and save the preview bundle

2. Make a review stub, not a synthetic forecast

Limits and failure modes

Next step