Skip to main content
POST
Preview Briefing On-Demand
Run a briefing on-demand from an ad-hoc prompt, without waiting for it to finish. Unlike Generate Briefing (POST /v1/briefings/sse), which streams the finished briefing back over SSE in the same request, this endpoint is fire-and-forget: it enqueues the run and returns immediately with a pending delivery handle. You then fetch the finished briefing by polling the delivery endpoints with the returned delivery_id. The output comes from the same engine behind your scheduled briefings, so it matches their depth, formatting, and citations — letting you preview a briefing before committing to a schedule.

Stock Selection

Scope the run to specific stocks in either of two ways (omit both to cover the full market):
  • stock_ids (recommended) — Internal stock UUIDs. Use the Map Tickers endpoint to convert ticker symbols to stock IDs first.
  • tickers — Ticker symbols (e.g. ["AAPL", "MSFT"]). Automatically resolved to stock IDs via the ticker mapping service. If a symbol cannot be resolved, the request returns BRIEFING_GENERATE_FAIL.
If both stock_ids and tickers are provided, stock_ids takes priority.

Polling for the result

The 202 response returns { delivery_id, status } with status: "pending" — the briefing is not ready yet. Poll GET /v1/briefings/deliveries/{delivery_id} until its status is terminal, then read the content from that response. status is the same field returned by Get Briefing Delivery.

previous_delivery_id

Pass the delivery_id of an earlier delivery to carry formatting and continuity from it into this run. The delivery must belong to your organization; otherwise the request returns BRIEFING_NOT_FOUND (see below).

Errors

Domain errors are returned as HTTP 200 with an error.code (and payload: null), consistent with the other briefing JSON endpoints. Input-validation failures are the exception — they return HTTP 400.

Authentication

For platform API keys, optionally pass user_id (the customer_id), user_email, and user_name in the request body to select which user the briefing runs as. Ordinary organization-bound keys resolve the user from the key itself and ignore these fields.

Authorizations

X-API-KEY
string
header
required

Body

application/json
query
string
required

The ad-hoc briefing prompt (used as the briefing topic), run through the briefing engine

tickers
string[]

Optional ticker symbols to scope the briefing; auto-resolved to stock_ids (stock_ids take priority). An unresolvable symbol returns BRIEFING_GENERATE_FAIL.

stock_ids
string[]

Optional internal stock ids to scope the briefing (preferred over tickers; no resolution needed)

language
string

Output language; auto-detected from the prompt when omitted

frequency
enum<string>

Data window (last 1 / 7 / 30 days, anchored at now). Defaults to daily.

Available options:
daily,
weekly,
monthly
timezone
string

IANA timezone (e.g. America/New_York) for the window and timestamps. Defaults to UTC.

previous_delivery_id
string<uuid>

A prior briefing delivery (that you own) to carry formatting/continuity from. Returns BRIEFING_NOT_FOUND if not owned.

user_id
string

User ID (customer_id) for platform API keys

user_email
string

User email for platform API keys

user_name
string

User name for platform API keys

Response

Domain error — returned with HTTP 200 and an error.code (payload null), consistent with the other briefing JSON endpoints. BRIEFING_NOT_FOUND when previous_delivery_id is not owned by the caller; BRIEFING_GENERATE_FAIL for a generic upstream/generation failure (including a tickers symbol that cannot be resolved to a stock).

Standard error response wrapper

error
object
required
payload
any | null
required

Always null for error responses