> ## Documentation Index > Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt > Use this file to discover all available pages before exploring further. # Served data > Understand the served-record model for data extracted from documents, show a user exactly where a value came from, and know how current each read is. Served data is the platform's model for records extracted from documents. The [extraction pipeline](/connections/indexing-and-extraction) reads your connected documents and projects what it finds into served records: effective-dated, traced to the document they came from, and cited field by field, so your application can show a user the page behind a value instead of asking them to trust it. Served records are read through read-only `GET` routes. Which record families exist is decided by the connection's document profile: a fixed set, with the families and their fields fixed in code for each profile. This page describes the model every family follows. ## Effective-dated versions Served records are effective-dated. When a record changes, the platform closes the current version by setting its end date and writes a new version. The current version of a record is the one with no end date. Nothing is deleted: a version that is closed stays as history. Reads serve current versions only. With [delivery](/connections/delivery#versioning), your warehouse keeps each version it received and closes it when a newer one arrives. ## Provenance A served record carries a `provenance` object that traces it to its source: | Field | Meaning | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `source_blob_ref` | The document the record came from. Null when no source was recorded. Pass it unchanged to open the document (below). | | `extraction_run_id` | The extraction that produced the record. Null when none was recorded. | | `effective_from` | When this version became current. | | `source_removed_at` | Present when every copy of the source document was removed from your library. See [Why a field is null](#why-a-field-is-null). | ## Credentials | Route | Organization API key (`nx__...`) | Scoped key (`nxsk_v1_...`) | | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Served-record reads | Admitted | Needs `catalog:read` | | Document listing and opening (`GET /api/v1/catalog/documents` and `GET /api/v1/catalog/documents/{source_blob_ref}`) | Admitted for the `live` environment key only. Any other environment's key gets `403 scoped_key_required`. | Needs `catalog:documents:read`, which no key carries by default. Nexio adds it to a key on request. | See [Authentication](/authentication) for both credential types. ## Connection pinning Every served-data read reads one active document library connection. * One active connection: `connection_id` is optional. * More than one: `connection_id` is required. Without it, the request fails with `400 catalog_connection_ambiguous`. * A `connection_id` that is not an active connection of your organization fails with `404 not_found`. A pinned client never silently reads zero rows. * No active connection: list routes return an empty page, and routes that read one record or one document return `404`. ## Pagination Most list routes use page numbers. The document listing pages by cursor instead (`limit` and `page.next_cursor`). | Parameter | Default | Bounds | | ----------- | ------- | ---------------------------------------------------- | | `page` | 1 | 1 to 10,000,000. Outside that range: `400`. | | `page_size` | 25 | Values above 100 are clamped to 100. Below 1: `400`. | A route's compact view can allow larger pages with a different bound; its endpoint page states it. Each numbered page carries `page`, `page_size`, `total_matched` (rows matching your filters) and `total_corpus` (rows in the whole connection). The counts and the items are separate reads, so a change served during the request can leave them briefly out of step. Some list routes also return `facets`: the labels available to filter on across the connection, computed without your filters. ## Freshness Most served-data reads are cached on the server for up to 30 seconds per organization and connection, so a change is visible to readers within 30 seconds of being served. Some reads are computed on every request instead; each endpoint page says whether its read is cached. How quickly a change in your source library becomes served is covered in [Sync health](/connections/sync-health). Served-data `GET` requests share the data-reads budget of 30,000 requests per minute per organization with the `/api/v1/records` reads. See [Limits](/reference/limits). ## Citations A served record whose fields can be cited carries a `citations` object. It is how a user checks a value against the page it came from without leaving your product. This section is the one definition of citations; the endpoint pages link here. The object is keyed by the response field it cites, so you look it up by the field you are rendering. One passage that states two fields appears under both keys. An empty object means the record states nothing a citation could attach to; `provenance.source_blob_ref` can still name the document. Each endpoint page lists the keys its records can carry. | Field | Type | Meaning | | ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source_blob_ref` | string or null | The document. Pass it unchanged to [open the document](#open-the-document-behind-a-citation). | | `field_path` | string or null | Where the value sits in the extraction. | | `quote` | string or null | The evidence text stored for the value: the passage read from the document, or a label where no passage was stored. Some families store none, so it is always null there. | | `page` | integer or null | 1-based page number. Null at `document` grain. | | `region` | object or null | `{x, y, w, h}`, normalized 0 to 1 with a top-left origin. Null unless `grain` is `region`. | | `grain` | string | How precisely the passage was located. Always present. | ### Read `grain` before you render | `grain` | What is known | What to render | | ---------- | ---------------------------------------------------- | ------------------------------------------------------- | | `region` | The passage was located in the page's word geometry. | The page, with a box over the exact words. | | `page` | The page, but not the rectangle. | The page, with the evidence text. | | `document` | Only the document. | The document, with the evidence text when there is one. | * Not every family reaches every grain. Handle all three. * A rectangle is never guessed. The platform computes it from the document's own word positions; a model never supplies coordinates. A missing rectangle means the platform could not place the passage on a page, so never draw a `document` citation as if it were a `region` one. * Multiply the rectangle by the rendered page box, never by a point size, so the box covers the same words at any zoom. * Treat an unrecognized `grain` value as `document`. ## Field removal for an acting person When your server asserts `X-Nexio-Acting-Principal` (the person a request acts for), reads that apply field removal are narrowed to what that person's seat may see. Field removal is applied route by route, and a route that applies none serves the same body with or without the header. | Read | What is removed for a restricted seat | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Served records | On reads that apply field removal: the fields the seat's policy denies, and the citations and document references of document classes the seat cannot open. Other extracted values stay. A read that applies none serves its values and citations to a restricted seat unchanged. | | Document listing | Documents of classes the seat cannot open are not listed. | | Opening a document | The request is refused with `403 document_class_not_open`, or with `403 document_unclassified` when no accepting pass has classified the document. | A seat whose policy cannot be read is served with every restricted field removed. How a seat's policy follows from your own systems is on [Access plane](/data-services/access). ## Why a field is null Served data never fills a gap with a guess. * A value is null when the document does not state it. A zero placeholder is never served as a value. * An empty list means no document stating it was found, not a verified absence. * `provenance.source_removed_at`, when present, is when every copy of the source document was removed from your library. Removing a document closes the current records traced to it, so reads stop serving them, and an earlier version from another document can become current in their place. Records of a family the removal step does not close stay served, and some of those families carry `source_removed_at`. Closed records are kept as history. See [Indexing and extraction](/connections/indexing-and-extraction#when-a-document-changes-or-disappears). ## Example: a served record with its citations Every served record follows the same shape: the family's own fields, a `provenance` object and a `citations` object keyed by the field each citation supports. The two fields `rate_new` and `rate_renewal` stand in for any family's fields. ```json Served record theme={null} { "id": "9932cf92-4c53-460f-ab67-b538786663c6", "rate_new": 15, "rate_renewal": 12.5, "provenance": { "source_blob_ref": "harbor-supply/price_schedule/1ceeae2456181c3ea9c33b0adbf78fb332a98d361fa603ffb665da4f8ab538a1", "extraction_run_id": "a81d9ebb-90dd-45ee-a922-35fc9a1c461f", "effective_from": "2026-09-02T14:05:11Z" }, "citations": { "rate_new": { "source_blob_ref": "harbor-supply/price_schedule/1ceeae2456181c3ea9c33b0adbf78fb332a98d361fa603ffb665da4f8ab538a1", "field_path": "price_schedule/lines/2/verbatim_quote", "quote": null, "page": 4, "region": { "x": 0.11, "y": 0.42, "w": 0.63, "h": 0.03 }, "grain": "region" }, "rate_renewal": { "source_blob_ref": "harbor-supply/price_schedule/1ceeae2456181c3ea9c33b0adbf78fb332a98d361fa603ffb665da4f8ab538a1", "field_path": "price_schedule/lines/2/verbatim_quote", "quote": null, "page": 4, "region": { "x": 0.11, "y": 0.42, "w": 0.63, "h": 0.03 }, "grain": "region" } } } ``` The two fields are stated in one passage, so both citation keys point to the same region on page 4. ## Open the document behind a citation Opening a document returns a short-lived URL for the file named by `source_blob_ref`. Request it from your server, then hand the URL to your viewer. Never send your API key to a browser. The URL is valid for 300 seconds; do not store it. The credentials the request needs are in [Credentials](#credentials), and the refusals are in [Errors](#errors). `page_count` in the answer is null when the document's text recorded no page signal, which is normal for Office files. Render by what your viewer shows rather than treating null as zero pages. ## Errors Every error uses the standard envelope. See [Errors](/reference/errors). | Status | Code | Cause | Fix | | ------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | 400 | `invalid_request` | A parameter is out of bounds (page, page size, a two-letter state, a UUID, a length limit, an unknown `view`). | Correct the parameter named in the message. | | 400 | `catalog_connection_ambiguous` | Your organization has more than one active connection. | Pass `connection_id`. | | 401 | `unauthorized` | Missing or invalid key. | Send a valid key as `Authorization: Bearer`. | | 403 | `insufficient_capability` | A scoped key lacks `catalog:read` (or `catalog:documents:read` on documents). | Ask Nexio to add the capability. | | 403 | `scoped_key_required` | Documents route called with a non-live environment key. | Use the live key or a scoped key with `catalog:documents:read`. | | 403 | `document_type_not_servable` | A call with no acting person asked for a document that is not classified as one of the classes open to calls without an acting person. | Show the citation as text, or send the acting person. | | 403 | `document_class_not_open` | The acting person's seat may not open this class of document. | Show the citation as text. | | 403 | `document_unclassified` | An acting person asked for a document whose class must be confirmed by an accepting extraction pass, and no such pass has classified it. | Show the citation as text. | | 404 | `not_found` | Unknown record key, unbacked document, inactive `connection_id`, or no active connection on a single-record read. | Check the key or `connection_id`. | | 429 | `rate_limited` | Over the data-reads budget. | Wait for `Retry-After` seconds. | | 500 | `presign_failed` | The object store could not sign a document URL. | Retry with backoff. | | 501 | `object_store_unconfigured` | Documents route on a deployment with no object store. | Show the citation at its grain, as text. | | 503 | `auth_unavailable` | Key verification is temporarily unavailable. | Retry with backoff. | How documents become served records. What stands behind each served value.