---
title: "Api Ai Retrieve"
method: GET
path: "/api/ai/retrieve"
---

# Api Ai Retrieve

`GET /api/ai/retrieve`

## Request

- Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from)
- URL: `https://www.oxfordledge.com/api/ai/retrieve`
- Auth: none declared

BM25 retrieval over SEC filing chunks for a ticker.

Returns: {ticker, query, count, chunks: [{id, ticker, accession, filing_type,
         section, chunk_text, filed_at, url, score}]}

## Query parameters

- `ticker` string, required
- `q` string, required: Query text
- `k` integer

## Response `200`

Successful Response

- AIRetrieveResponse: `/api/ai/retrieve` — BM25 retrieval over SEC filing chunks. F4 boundary backfill 2026-05-08 (Initiative 6). `static/js/ask-ai.ts` iterates `chunks` for the `<retrieved_excerpts>` prompt block and the citation tooltip + drawer, reading chunk_text / filed_at / filing_type / section / url. (Corrected 2026-09-22: this used to say the card renders "ticker echo, accession link, filed_at, score" — measured against the frontend, none of those three has a reader.)
  - `ticker` string, required: Uppercase ticker echo of the request param.
  - `query` string, required: Echo of the user's query (whitespace-trimmed).
  - `count` integer, required: len(chunks). Equal to k unless the corpus has fewer matches.
  - `chunks` FilingChunk[], required: Retrieved filing chunks, ranked by `score`. TYPED as of 2026-09-22 (it was an untyped `list`, which is why `response_model=` filtered nothing and the raw pgvector `cosine_dist` reached the wire). The item model is an allow-list: fields it does not declare are dropped, which is a second, independent control beside the registry-derived strip in `services.rag_indexer.strip_vendor_only_fields`.
    - `id` integer, required: filing_chunks.id — stable chunk identifier.
    - `ticker` string, required: Ticker the chunk was indexed under. May be a share-class sibling of the requested symbol (PR-G5 §2.5 UNION).
    - `accession` string, required: SEC accession number of the source filing.
    - `chunk_text` string, required: The passage, trimmed to 1200 chars and defanged of forged `<retrieved_excerpts>` markers (DARTLAB-4).
    - `chunk_index` integer, required: Ordinal of this chunk within its filing section.
    - `score` number, required: Relevance score. RANK-DERIVED, not a similarity magnitude: ts_rank on the lexical arm, the section-weighted RRF sum on the hybrid arm. Never the cosine distance.
    - `filing_type` string, nullable: e.g. '10-K', '10-Q'. Nullable in the DDL.
    - `section` string, nullable: Filing section the chunk came from. Nullable in the DDL.
    - `filed_at` string, nullable: Filing date as stored — filing_chunks.filed_at is TEXT, not DATE. Nullable in the DDL.
    - `url` string, nullable: Deep link to the source filing on sec.gov. Nullable in the DDL.
  - `mode` string, required: Retrieval backend used: 'sqlite-bm25' or 'pg-bm25'. Telemetry / debugging field.
  - `latency_ms` integer, required: Wall-clock retrieval latency. Telemetry / debugging field.
  - `searchesRemaining` integer, nullable: Filing searches left today on the user's daily allowance (dedicated 25/day-free counter; does not consume AI credits). BOARD 2026-07-21.
  - `dailyLimit` integer, nullable: The user's daily filing-search allowance for their tier (free = 25).

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)