Flux logo
Flux
Docs
Concepts

Concepts

Understanding the response

What each part of a Search or Lineage passage means, and how to use it in your code.

5 min read · Updated 20 Nov 2026
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);
results[0]
{  "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:

Response
{  "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.

The note
[who: he -> Halvard Lindqvist | when: May 12 -> May 12, 2026 (year inferred)]
  • who names the person or organisation behind a pronoun or a description.
  • what names the thing or event behind a description such as the event.
  • when completes 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 is published.

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);  }}
Output
time May 12 -> May 12, 2026person he -> Halvard Lindqvistplace Uppsala -> Uppsala

span

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:

From a 1,498-token article, trimmed
{  "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);

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 your enrich count or the page could not be read. lineage is null.
  • pending: still being read when the search returned. Ask again to get it.
Search response, trimmed
{  "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 sources this 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.threshold are 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.

Next steps