> ## Documentation Index > Fetch the complete documentation index at: https://docs.linqalpha.com/llms.txt > Use this file to discover all available pages before exploring further. # Preview Briefing On-Demand > Run a briefing on-demand from an ad-hoc prompt as a fire-and-forget job: enqueue the run and get a pending delivery handle immediately, then poll `GET /v1/briefings/deliveries/{delivery_id}` for the result. Run a briefing on-demand from an ad-hoc prompt, without waiting for it to finish. Unlike [Generate Briefing](/api-reference/briefing/generate) (`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](/api-reference/briefing/delivery-detail) 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](/api-reference/basic/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](/api-reference/briefing/delivery-detail). ## `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`. | Condition | HTTP status | `error.code` | | ------------------------------------------------ | ----------- | ------------------------ | | `query` missing or empty | `400` | `INVALID_REQUEST_BODY` | | `previous_delivery_id` is not a valid UUID | `400` | `INVALID_REQUEST_BODY` | | `previous_delivery_id` not owned by the caller | `200` | `BRIEFING_NOT_FOUND` | | A `tickers` symbol cannot be resolved to a stock | `200` | `BRIEFING_GENERATE_FAIL` | | Upstream / generation failure | `200` | `BRIEFING_GENERATE_FAIL` | ## 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. ## OpenAPI ````yaml POST /v1/briefings/preview openapi: 3.0.1 info: title: LinqAlpha API description: >- Linq helps finance professionals make informed decisions using Retrieval-Augmented Generation (RAG)-enhanced answers. By leveraging cutting-edge Large Language Models (LLM) and supplementary technology, Linq provides the most optimized responses based on your queries. version: 1.0.0 license: name: MIT servers: - url: https://api.linqalpha.com security: - ApiKeyAuth: [] tags: - name: Search description: Search and generate responses - name: Data description: Data retrieval and mapping - name: Feedback description: Conversation feedback - name: RMS description: Research Management System - name: Source Management description: Source batch and file management - name: MCP description: >- LinqAlpha MCP — Financial data tools for AI assistants via Model Context Protocol - name: Connectors description: Customer Connectors — customer-owned MCP connector management - name: Briefing description: Briefing Agent — automated market briefings with scheduling and delivery - name: Status description: Sync status — check organization, document, and container sync progress paths: /v1/briefings/preview: post: tags: - Briefing summary: Preview Briefing On-Demand description: >- Run a briefing on-demand from an ad-hoc prompt as a fire-and-forget job: enqueue the run and get a pending delivery handle immediately, then poll `GET /v1/briefings/deliveries/{delivery_id}` for the result. operationId: briefingPreview requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string description: >- The ad-hoc briefing prompt (used as the briefing topic), run through the briefing engine tickers: type: array items: type: string description: >- 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: type: array items: type: string description: >- Optional internal stock ids to scope the briefing (preferred over tickers; no resolution needed) language: type: string description: Output language; auto-detected from the prompt when omitted frequency: type: string enum: - daily - weekly - monthly description: >- Data window (last 1 / 7 / 30 days, anchored at now). Defaults to daily. timezone: type: string description: >- IANA timezone (e.g. America/New_York) for the window and timestamps. Defaults to UTC. previous_delivery_id: type: string format: uuid description: >- A prior briefing delivery (that you own) to carry formatting/continuity from. Returns BRIEFING_NOT_FOUND if not owned. user_id: type: string description: User ID (customer_id) for platform API keys user_email: type: string description: User email for platform API keys user_name: type: string description: User name for platform API keys responses: '200': description: >- 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). content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: error: code: BRIEFING_NOT_FOUND msg: Brief delivery not found. message: Brief delivery not found. payload: null '202': description: >- Accepted — the run was enqueued and a pending delivery handle is returned. The briefing is not ready yet; poll `GET /v1/briefings/deliveries/{delivery_id}` with the returned `delivery_id` until its status is terminal. content: application/json: schema: type: object properties: error: type: object nullable: true payload: type: object properties: delivery_id: type: string format: uuid description: >- Handle for the enqueued run; poll the delivery endpoints with this id status: type: string description: >- Delivery status; `pending` immediately after enqueue (same `status` field as Get Delivery Detail) example: error: null payload: delivery_id: b1f2c3d4-5678-90ab-cdef-1234567890ab status: pending '400': description: >- Bad Request - Invalid request parameters (e.g. missing `query`, or `previous_delivery_id` not a valid UUID). content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: error: code: INVALID_REQUEST_BODY msg: query is required and must be a string message: query is required and must be a string payload: null '401': description: Unauthorized - Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: error: code: API_KEY_MISSING msg: header does not contain api key message: header does not contain api key payload: null components: schemas: ApiErrorResponse: type: object description: Standard error response wrapper properties: error: $ref: '#/components/schemas/ApiError' payload: description: Always null for error responses nullable: true required: - error - payload ApiError: type: object properties: code: type: string description: >- Error code indicating the type of error. Common codes: - Authentication: `API_KEY_MISSING`, `INVALID_API_KEY` - Validation: `INVALID_REQUEST_BODY`, `ORGANIZATION_ID_MISSING`, `TICKERS_MISSING`, `CHAT_MESSAGE_ID_MISSING`, `DOCUMENT_ID_MISSING` - Service: `SEARCH_FAIL`, `TTS_FAIL`, `CREATE_CONV_FAIL`, `GET_STOCK_FAIL`, `CREATE_MSG_FAIL`, `ALPHA_COMP_FAIL`, `GET_REF_FAIL` - Connectors: `CONNECTOR_LIST_FAIL`, `CONNECTOR_NOT_FOUND`, `CONNECTOR_CREATE_FAIL`, `CONNECTOR_UPDATE_FAIL`, `CONNECTOR_DELETE_FAIL`, `CONNECTOR_TEST_FAIL` - Not Found: `NOT_FOUND` example: INVALID_REQUEST_BODY msg: type: string description: Error message (deprecated, use `message` instead) example: query is required and must be a string message: type: string description: Error message providing more details about the error example: query is required and must be a string required: - code securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ````