Concepts
Understanding the response
What each part of a Search or Lineage passage means, and how to use it in your code.
On this page
Search and Lineage return passages. A passage is one sentence or short run of sentences from a page, plus the context a model needs to read it on its own. This page takes one real passage apart, field by field.
One passage
This request sends a short paragraph and one question. The passage that answers it mentions he and May 12, but the name is in the sentence before, and the year is only in the publication date.
curl https://fluxsearch.io/api/v1/lineage \ -H "Authorization: Bearer $FLUX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text":"Halvard Lindqvist is chief engineer at the Nordic Grid Authority. On May 12, he led the team that connected the first sodium-ion storage site to the grid near Uppsala. The site stores 20 MWh. It was built in eleven months, and the authority plans three more like it.","queries":["What did the chief engineer deliver, and when?"],"published":"2026-09-14"}'import osimport requestsresponse = requests.post( "https://fluxsearch.io/api/v1/lineage", headers={"Authorization": f"Bearer {os.environ['FLUX_API_KEY']}"}, json={ "text": "Halvard Lindqvist is chief engineer at the Nordic Grid Authority. On May 12, he led the team that connected the first sodium-ion storage site to the grid near Uppsala. The site stores 20 MWh. It was built in eleven months, and the authority plans three more like it.", "queries": ["What did the chief engineer deliver, and when?"], "published": "2026-09-14", }, timeout=120,)response.raise_for_status()data = response.json()print(data)const response = await fetch("https://fluxsearch.io/api/v1/lineage", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ text: "Halvard Lindqvist is chief engineer at the Nordic Grid Authority. On May 12, he led the team that connected the first sodium-ion storage site to the grid near Uppsala. The site stores 20 MWh. It was built in eleven months, and the authority plans three more like it.", queries: ["What did the chief engineer deliver, and when?"], published: "2026-09-14", }),});if (!response.ok) throw new Error(`Flux ${response.status}: ${await response.text()}`);const data = await response.json();console.log(data);{ "id": "res_1", "source_id": "src_1", "text": " On May 12, he led the team that connected the first sodium-ion storage site to the grid near Uppsala.", "enriched_text": " On May 12, he led the team that connected the first sodium-ion storage site to the grid near Uppsala. [who: he -> Halvard Lindqvist | when: May 12 -> May 12, 2026 (year inferred)]", "enrichment": "inline", "span": { "start": 65, "end": 167 }, "score": 0.7734513878822327, "annotations": [ { "type": "time", "text": "May 12", "start_index": 4, "end_index": 10, "canonical": "May 12, 2026", "year_inferred": true }, { "type": "person", "text": "he", "start_index": 12, "end_index": 14, "canonical": "Halvard Lindqvist" }, { "type": "place", "text": "Uppsala", "start_index": 94, "end_index": 101, "canonical": null } ]}The whole response, with the parts that describe the request as a whole:
{ "request_id": "req_f508e48a575e48d39497f362", "status": "completed", "query": "What did the chief engineer deliver, and when?", "sources": [ { "id": "src_1", "url": null, "published_at": "2026-09-14", "input_tokens": 65 } ], "results": [ { "id": "res_1", "source_id": "src_1", "text": " On May 12, he led the team that connected the first sodium-ion storage site to the grid near Uppsala.", "enriched_text": " On May 12, he led the team that connected the first sodium-ion storage site to the grid near Uppsala. [who: he -> Halvard Lindqvist | when: May 12 -> May 12, 2026 (year inferred)]", "enrichment": "inline", "span": { "start": 65, "end": 167 }, "score": 0.7734513878822327, "annotations": [ { "type": "time", "text": "May 12", "start_index": 4, "end_index": 10, "canonical": "May 12, 2026", "year_inferred": true }, { "type": "person", "text": "he", "start_index": 12, "end_index": 14, "canonical": "Halvard Lindqvist" }, { "type": "place", "text": "Uppsala", "start_index": 94, "end_index": 101, "canonical": null } ] } ], "selection": { "score_type": { "name": "relevance", "higher_is_better": true, "calibrated": false }, "threshold": 0.1, "considered": 4, "returned": 1, "examined_tokens": 65, "enriched_results": 1, "retained_ratio": 0.89231, "reduction_ratio": 0.10769 }, "usage": { "input_tokens": 65, "output_tokens": 58, "cost_usd": "0.0000065000", "cost_usd_ticks": 65000 }}text
The sentence exactly as the source has it, character for character. Show this to people and quote it, because it is what the page says.
enriched_text
The same sentence with a note at the end that fills in what it leaves out. Send this to your model. A model reading only text cannot tell who he is or which year it was.
[who: he -> Halvard Lindqvist | when: May 12 -> May 12, 2026 (year inferred)]whonames the person or organisation behind a pronoun or a description.whatnames the thing or event behind a description such asthe event.whencompletes a partial date.- Each part reads
mention -> resolution. Several parts are joined with|. (year inferred)means the text gave no year, so it came from the page's date. Here that ispublished.
When nothing needs filling in, enriched_text equals text and enrichment is none. It is never null, so you can always send it.
passages = [r['enriched_text'].strip() for r in data['results']]prompt = "Answer from these passages:\n" + "\n".join(passages)print(prompt)const passages = data.results.map((r: { enriched_text: string }) => r.enriched_text.trim());const prompt = `Answer from these passages:\n${passages.join("\n")}`;console.log(prompt);annotations
The people, organisations, places and dates in the passage, as data. start_index and end_index are character offsets into text. canonical is the resolved form, or null when the mention needed nothing.
Use them to highlight names in your UI, or to collect every entity a set of results mentions:
for passage in data['results']: for a in passage['annotations']: mention = passage['text'][a['start_index']:a['end_index']] print(a['type'], mention, '->', a['canonical'] or mention)for (const passage of data.results) { for (const a of passage.annotations) { const mention = passage.text.slice(a.start_index, a.end_index); console.log(a.type, mention, "->", a.canonical ?? mention); }}time May 12 -> May 12, 2026person he -> Halvard Lindqvistplace Uppsala -> Uppsalaspan
Where the passage sits in the source, as character offsets. source[span.start:span.end] is exactly text, so you can highlight the sentence in the original document or link to it.
score
How well the passage answers the question, higher is better. Passages under selection.threshold are left out. Use scores to rank passages within one response. They are not calibrated, so comparing them across requests means little.
source_id and sources
Each passage carries a source_id. Look it up in sources to get the URL, the published_at date and the tokens read. For your own text, url is null.
The whole response
selection
considered is how many passages Lineage scored and returned how many it kept. examined_tokens is the size of the source and retained_ratio the share of it you get back. On a long page this is where the saving shows:
{ "request_id": "req_5c349de866094ab492a11ce8", "status": "completed", "query": "What did CATL agree with HyperStrong?", "sources": [ { "id": "src_1", "url": "https://www.batterytechonline.com/design-manufacturing/how-catl-moved-sodium-ion-batteries-from-lab-chemistry-to-gwh-scale-reality", "published_at": "2026-08-05", "input_tokens": 1498 } ], "results": [ { "id": "res_9", "source_id": "src_1", "text": "In April of this year, CATL and energy storage integrator HyperStrong signed a strategic cooperation agreement in Ningde, China, covering a three-year, 60 GWh sodium-ion battery supply commitment.", "enriched_text": "In April of this year, CATL and energy storage integrator HyperStrong signed a strategic cooperation agreement in Ningde, China, covering a three-year, 60 GWh sodium-ion battery supply commitment.", "enrichment": "none", "span": { "start": 3211, "end": 3407 }, "score": 0.8612760305404663, "annotations": [ { "type": "time", "text": "April of this year", "start_index": 3, "end_index": 21, "canonical": null }, { "type": "organisation", "text": "CATL", "start_index": 23, "end_index": 27, "canonical": null }, { "type": "organisation", "text": "HyperStrong", "start_index": 58, "end_index": 69, "canonical": null }, { "type": "place", "text": "Ningde", "start_index": 114, "end_index": 120, "canonical": null }, { "type": "place", "text": "China", "start_index": 122, "end_index": 127, "canonical": null }, { "type": "time", "text": "three-year", "start_index": 140, "end_index": 150, "canonical": null } ] }, { "id": "res_10", "source_id": "src_1", "text": " CATL describes the agreement as the largest sodium-ion battery supply deal in the world to date, and HyperStrong as the company's first strategic partner for sodium-ion energy storage.", "enriched_text": " CATL describes the agreement as the largest sodium-ion battery supply deal in the world to date, and HyperStrong as the company's first strategic partner for sodium-ion energy storage. [who: the agreement -> CATL and HyperStrong’s 60-GWh sodium-ion agreement]", "enrichment": "inline", "span": { "start": 3407, "end": 3592 }, "score": 0.5569056272506714, "annotations": [ { "type": "organisation", "text": "CATL", "start_index": 1, "end_index": 5, "canonical": null }, { "type": "organisation", "text": "the agreement", "start_index": 16, "end_index": 29, "canonical": "CATL and HyperStrong’s 60-GWh sodium-ion agreement" }, { "type": "organisation", "text": "HyperStrong", "start_index": 102, "end_index": 113, "canonical": null } ] } ], "selection": { "score_type": { "name": "relevance", "higher_is_better": true, "calibrated": false }, "threshold": 0.1, "considered": 74, "returned": 12, "examined_tokens": 1498, "enriched_results": 2, "retained_ratio": 0.25634, "reduction_ratio": 0.74366 }, "usage": { "input_tokens": 1498, "output_tokens": 384, "cost_usd": "0.0001498000", "cost_usd_ticks": 1498000 }}usage
cost_usd is a decimal string, so it never loses precision. cost_usd_ticks is the same amount as an integer, in units of $0.0000000001. Add up ticks if you track spend in code.
from decimal import Decimalprint(Decimal(data['usage']['cost_usd']))console.log(Number(BigInt(data.usage.cost_usd_ticks)) / 1e10);Passages in a search
A search returns ranked results. The first enrich of them are read for you, and their passages sit under results[].lineage.results with the same fields as above. snippet is the search engine's preview of the page and has no notes.
enrichment on each result says what happened:
inline: read, and at least one passage has a note.none: read, with nothing that needed filling in.skipped: not read, because it was past yourenrichcount or the page could not be read.lineageis null.pending: still being read when the search returned. Ask again to get it.
{ "request_id": "req_4cd56fca1b6546bb9b4e7913", "status": "completed", "query": "CATL HyperStrong sodium-ion supply agreement", "results": [ { "id": "res_1", "rank": 1, "provider_rank": 1, "url": "https://www.catl.com/en/news/6812.html", "title": "CATL and HyperStrong Sign the World's Largest Sodium-Ion Energy ...", "published_at": "2026-05-06", "snippet": "The two parties announced a three-year partnership covering 60GWh of sodium-ion battery supply, marking a significant milestone for the ...", "enrichment": "inline", "lineage": { "results": [ { "id": "res_1", "source_id": "res_1", "text": "On April 27, CATL and HyperStrong signed a strategic cooperation agreement on sodium-ion batteries for energy storage in Ningde, Fujian.", "enriched_text": "On April 27, CATL and HyperStrong signed a strategic cooperation agreement on sodium-ion batteries for energy storage in Ningde, Fujian. [when: April 27 -> Apr 27, 2026 (year inferred)]", "enrichment": "inline", "span": { "start": 107, "end": 243 }, "score": 0.951457381248474, "annotations": [ { "type": "time", "text": "April 27", "start_index": 3, "end_index": 11, "canonical": "Apr 27, 2026", "year_inferred": true }, { "type": "organisation", "text": "CATL", "start_index": 13, "end_index": 17, "canonical": null }, { "type": "organisation", "text": "HyperStrong", "start_index": 22, "end_index": 33, "canonical": null }, { "type": "place", "text": "Ningde", "start_index": 121, "end_index": 127, "canonical": null }, { "type": "place", "text": "Fujian", "start_index": 129, "end_index": 135, "canonical": null } ] }, { "id": "res_2", "source_id": "res_1", "text": " The two parties announced a three-year partnership covering 60GWh of sodium-ion battery supply, marking a significant milestone for the industrialization of sodium-ion batteries technology.", "enriched_text": " The two parties announced a three-year partnership covering 60GWh of sodium-ion battery supply, marking a significant milestone for the industrialization of sodium-ion batteries technology. [who: The two parties -> CATL and HyperStrong]", "enrichment": "inline", "span": { "start": 243, "end": 433 }, "score": 0.7018508315086365, "annotations": [ { "type": "organisation", "text": "The two parties", "start_index": 1, "end_index": 16, "canonical": "CATL and HyperStrong" } ] } ] } }, { "id": "res_3", "rank": 3, "provider_rank": 3, "url": "https://christopherchico.substack.com/p/catls-sodium-ion-order-still-has", "title": "CATL's sodium-ion order still has to prove the economics", "published_at": null, "snippet": "On April 27, 2026, CATL and HyperStrong announced a 60 GWh sodium-ion battery supply agreement for energy storage. The agreement covers supply ...", "enrichment": "skipped", "lineage": null } ], "filters": null, "answer": null, "related_queries": [ "CATL sodium-ion battery price", "CATL sodium-ion battery for sale", "CATL sodium-ion battery datasheet", "CATL sodium-ion battery for home", "CATL Naxtra", "CATL sodium-ion battery cell" ], "usage": { "searches": 1, "results_returned": 5, "results_enriched": 2, "cost_usd": "0.0040000000", "cost_usd_ticks": 40000000 }}Put it together
This script searches, numbers every passage, and builds a prompt your model can cite with [1], [2] and so on. The source list maps each number back to its page.
import osimport requestsAPI = "https://fluxsearch.io/api/v1"HEADERS = {"Authorization": f"Bearer {os.environ['FLUX_API_KEY']}"}QUESTION = "What did CATL and HyperStrong agree, and when?"response = requests.post( f"{API}/search", headers=HEADERS, json={"query": "CATL HyperStrong sodium-ion supply agreement", "max_results": 5, "enrich": 2}, timeout=120,)response.raise_for_status()passages, sources = [], []for result in response.json()["results"]: if not result["lineage"]: continue sources.append(f"[{len(sources) + 1}] {result['title']}\n {result['url']}") for passage in result["lineage"]["results"]: passages.append(f"[{len(sources)}] {passage['enriched_text'].strip()}")prompt = "\n".join( [ "Answer using only these passages. Cite each claim with its number.", "", *passages, "", f"Question: {QUESTION}", ])print(prompt)print()print("\n".join(sources))const API = "https://fluxsearch.io/api/v1";const QUESTION = "What did CATL and HyperStrong agree, and when?";type Passage = { enriched_text: string };type Result = { title: string; url: string; lineage: { results: Passage[] } | null };const response = await fetch(`${API}/search`, { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "CATL HyperStrong sodium-ion supply agreement", max_results: 5, enrich: 2, }),});if (!response.ok) throw new Error(`Flux ${response.status}: ${await response.text()}`);const { results } = (await response.json()) as { results: Result[] };const passages: string[] = [];const sources: string[] = [];for (const result of results) { if (!result.lineage) continue; sources.push(`[${sources.length + 1}] ${result.title}\n ${result.url}`); for (const passage of result.lineage.results) { passages.push(`[${sources.length}] ${passage.enriched_text.trim()}`); }}const prompt = [ "Answer using only these passages. Cite each claim with its number.", "", ...passages, "", `Question: ${QUESTION}`,].join("\n");console.log(prompt);console.log();console.log(sources.join("\n"));Field reference
Each passage
- id (required)string
- source_id (required)string
- Which entry of
sourcesthis came from. - text (required)string
- The passage exactly as it appears in your document.
- enriched_text (required)string
- The passage with context added only where it needs it, such as an exact date or the name behind "she". Never null: when there is nothing to add, it equals
text. - enrichment (required)Enrichment
- span (required)object
- Where the passage starts and ends in the document you sent.
- score (required)number | null
- How well the passage answers the query. Higher is better. Passages below
selection.thresholdare not returned. - annotations (required)Annotation[]
Each search result
- id (required)string
- rank (required)integer
- Position in the results, starting at 1.
- provider_rank (required)integer
- Where the search index ranked it, before Flux reordered the results.
- url (required)string
- The page address. Always present.
- title (required)string
- The page title. Empty if the index has none.
- published_at (required)string | null
- When the page was published, if the search index knows, as ISO at the precision known: "2024-09-24", "2026-07" for "3 months ago", "2022" for "4 years ago". Otherwise null.
- snippet (required)string
- The search index's summary of the page. Flux does not change it.
- enrichment (required)SearchEnrichment
- lineage (required)SearchLineage | null
- The passages Flux read from this page. Null when the page was not read.