---
title: Read spans
description: Returns the content of 1 to 50 spans that Search objects, Answer a question, or a run returned, with one result for each span, in order.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Read spans

`POST /v1/workspaces/{workspaceId}/read-spans`

Returns the content of 1 to 50 spans that Search objects, Answer a question, or a run returned, with one result for each span, in order. include names the parts: text (the default) is the text of a document, or the speech of a video or a recording with its lines. raw is the span cut from the object in its own format: a PDF of the pages, the text of a text file or a mail, the image, or a clip. object is the whole object version. delivery inline (the default) returns binary parts as base64 data, up to 20 MiB a call, and a url past that. url returns every binary part as a url, which works until its expiresAt. A large span returns in parts: the result span is the part returned, and next is the body of the next read, or null. A span that cannot be read has an error on its own result: not_found, invalid_span (the span does not fit the object), or content_unavailable (the content is not stored or cannot be read). The other spans still read. Requires the viewer role. Send the target of the search: a bucket or a dataset.

## Authentication

Send `Authorization: Bearer <GRAPHON_API_KEY>`. Read the key from the
GRAPHON_API_KEY environment variable. Never print it.

## Path parameters

- `workspaceId` (string) — The workspace id.

## Request body

- `target` (string) — What to query: a bucket id (bkt…) of this workspace with indexing enabled, or a dataset id (dst…) from List datasets.
- `spans` (Span[]) — The spans to read, 1 to 50, unchanged, as Search objects, Answer a question, or a run returned them.
- `include` (ReadInclude[] (optional)) — The parts to return for each span. Each fills the result field of the same name. Defaults to text.
- `delivery` (Delivery (optional)) — inline: each binary part as base64 data, up to 20 MiB a call in span order, and a url past that. url: each binary part as a url. One of: inline, url.

## Example request

```bash
curl \
  --url "https://api.beta.graphon.ai/v1/workspaces/wspq7ws2np5l8z4/read-spans" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"target":"bktA1b2C3d4E5","spans":[{"key":"manuals/pump.pdf","versionId":"ver_8a1d4c7e2b9f4e6a8c3d5b7f1e9a2c4d","unit":"chars","start":1200,"end":3400,"pages":{"start":3,"end":5}}],"include":["text"],"delivery":"inline"}'
```

## CLI

```bash
graphon read-spans support-tickets manuals/pump.pdf --version-id ver_8a1d4c7e2b9f4e6a8c3d5b7f1e9a2c4d --unit chars --start 1200 --end 3400 --include text
```

## Example response

```json
{
  "results": [
    {
      "span": {
        "key": "manuals/pump.pdf",
        "versionId": "ver_8a1d4c7e2b9f4e6a8c3d5b7f1e9a2c4d",
        "unit": "chars",
        "start": 1200,
        "end": 3400,
        "pages": {
          "start": 3,
          "end": 5
        }
      },
      "contentType": "application/pdf",
      "text": "## Seal check\n\nClose the inlet valve before you open the pump housing. Replace the seal when it shows cracks."
    }
  ],
  "next": null
}
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.