Embeddings

EMBEDDINGS QUICKSTART

Pulling embeddings

Embeddings come in two calls. First discover which quarters exist for a ticker with GET /v1/transcripts/{ticker}, which lists each fiscal_period and its chunk_count. Then pull the vectors for a quarter with GET /v1/embeddings/{ticker}?fiscal_period=YYYY-Qn. Each row is one transcript chunk: a 768-dimensional vector from gemini-embedding-2-preview plus the keys that point back to the source text. The API serves vectors, not prose, and does no server-side search, so you rank them yourself. The RAG guide shows the cosine-similarity step in Python and BigQuery. To see coverage and a worked sample, browse the Earnings Embeddings dataset.

bash

# 1. Which quarters are available for the ticker?
curl https://api.vectorfinancials.com/v1/transcripts/AAPL \
  -H "X-API-Key: vf_sk_your_key_here" -G -d "limit=4"

# Response: [{ "fiscal_period": "2026-Q2", "chunk_count": 142 }, ...]

# 2. Pull the embedding vectors for one quarter.
curl https://api.vectorfinancials.com/v1/embeddings/AAPL \
  -H "X-API-Key: vf_sk_your_key_here" \
  -G -d "fiscal_period=2026-Q2" -d "limit=2"

# Response: a JSON array of EmbeddingRecord
[
  {
    "ticker": "AAPL",
    "fiscal_period": "2026-Q2",
    "chunk_idx": 0,
    "embedding": [0.0123, -0.0456, 0.0789, /* ...765 more floats... */],
    "model_version": "gemini/gemini-embedding-2-preview",
    "effective_ts": "2026-05-01T21:00:00Z",
    "knowledge_ts": "2026-05-03T02:30:00Z"
  }
]

Embed your query with the same model and task_type="retrieval_query" (the stored chunks use retrieval_document), or cosine similarity is silently wrong. To join a matched vector back to readable text, key on (ticker, fiscal_period, chunk_idx) against the raw transcript text shared alongside the embeddings.

Embedding model

Every vector is produced by Google's gemini-embedding-2-preview, the same model across the whole corpus, so your query embeddings line up with it as long as you call that model. We pin one model id rather than mixing versions; when we move to a new one it lands in the model_version field on every row so you can tell vectors apart.

The model is trained with Matryoshka Representation Learning, which means a long embedding can be truncated to a shorter prefix and stay useful. Google's default output is 3072 dimensions, truncatable down to 128, with 768, 1536, and 3072 the recommended sizes. We store the 768-dimensional output, which keeps the table compact while staying in Google's recommended range, and the gemini-embedding-2 family normalizes the truncated vector for you.

For the authoritative spec, including dimensionality and how to phrase a retrieval query versus a stored document, see Google's Gemini API embeddings guide and the embeddings task-type reference.

Coverage & update cadence

Today the corpus is earnings-call transcripts across the S&P 500, in beta. SEC filing embeddings are in preview and not yet served on the public API. The roadmap is to widen coverage to 5,000+ tickers and backfill the history at general availability.

The pipeline runs weekly. As new transcripts land upstream they get chunked per fiscal period, embedded, and appended to the Iceberg table. Nothing is ever rewritten in place, so a quarter you pulled last week returns the same vectors this week, and new quarters simply show up. Every chunk is bitemporal: effective_ts is the period the call belongs to and knowledge_ts is when we embedded it, so you can reconstruct exactly what was knowable on any past date.

Embeddings field reference

Every field returned by GET /v1/embeddings/{ticker} and the discovery endpoint GET /v1/transcripts/{ticker}, with its type and how to read it.

Field	Type	Nullable	Meaning & how to use
`ticker`	`string`	no	Equity ticker symbol (e.g. AAPL). Echoes your request.
`fiscal_period`	`string (YYYY-Qn)`	no	Fiscal quarter the chunk belongs to, e.g. 2026-Q2. Required query param on /v1/embeddings; discover valid values with /v1/transcripts.
`chunk_idx`	`integer`	no	Zero-based position of the chunk within the transcript. Join key back to your own transcript text on (ticker, fiscal_period, chunk_idx).
`embedding`	`number[768]`	no	768-dim vector from gemini-embedding-2-preview (stored as task_type retrieval_document). Rank by cosine similarity against a query embedded with retrieval_query.
`model_version`	`string`	no	Model that produced the vector, e.g. gemini/gemini-embedding-2-preview. Embed your query with the same model or similarity breaks.
`effective_ts`	`string (ISO 8601)`	no	When the chunk became effective (the earnings call / period date).
`knowledge_ts`	`string (ISO 8601)`	no	When VectorFin embedded and ingested this version. Filter on it for point-in-time RAG with no look-ahead.
`chunk_count`	`integer`	no	Returned by /v1/transcripts only: how many chunks exist for that fiscal_period, so you can page through /v1/embeddings.