Graphon Docs

Query a dataset

Find a dataset in the catalog, then search it, read spans, ask it a question, and research it with its dataset id as the target.

Overview

This guide finds a dataset in the catalog and queries it. A dataset takes the same calls as a bucket. The only change is target: send the dataset id in place of a bucket id. Read Datasets for what a dataset is, and how it differs from a bucket.

Before you start

You need a workspace and an API key with the Viewer role or higher. Export GRAPHON_API_KEY and GRAPHON_WORKSPACE_ID, as in Setup your environment. You upload and index nothing: Graphon curates the dataset and keeps it indexed.

Find a dataset

List datasets returns the published datasets, most recently indexed first. Each one carries its id, its source and license, example questions, and the access of your workspace. Get a dataset takes the id or the slug.

CLI

graphon datasets list
graphon datasets list --category legal
graphon datasets get us-case-law

cURL

curl --request GET \
  --url "https://api.beta.graphon.ai/v1/workspaces/$GRAPHON_WORKSPACE_ID/datasets?category=legal" \
  --header "Authorization: Bearer $GRAPHON_API_KEY"

Response

{
  "datasets": [
    {
      "id": "dstC4s3L4w0x1",
      "slug": "us-case-law",
      "title": "US case law",
      "summary": "Opinions of the US Supreme Court and the federal courts of appeals.",
      "description": "Published opinions of the US Supreme Court and the federal courts of appeals, as plain text.",
      "category": "legal",
      "source": {
        "name": "CourtListener",
        "url": "https://www.courtlistener.com",
        "license": "Public domain"
      },
      "documentCount": 412904,
      "indexedBytes": "8392045113",
      "indexedAt": "2026-10-26T04:12:00.000Z",
      "examples": [{ "query": "Which cases overruled Chevron?", "mode": "answer" }],
      "access": { "price": { "kind": "free" }, "state": "open" }
    }
  ],
  "nextCursor": null
}

Copy the id. The query calls take the id only, never the slug. A dataset with access.state locked is paid, and your workspace cannot query it yet.

Search a dataset

CLI

graphon search dstC4s3L4w0x1 "qualified immunity excessive force"

cURL

curl --request POST \
  --url "https://api.beta.graphon.ai/v1/workspaces/$GRAPHON_WORKSPACE_ID/search" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "target": "dstC4s3L4w0x1",
    "query": "qualified immunity excessive force",
    "limit": 5
  }'

Response

{
  "results": [
    {
      "key": "scotus/2015/mullenix-v-luna.txt",
      "versionId": "ver_8b2e6d1f4a9c4e7b9d3a5f0c2e8b6d41",
      "contentType": "text/plain",
      "rank": 1,
      "score": 0.81,
      "spans": [
        {
          "key": "scotus/2015/mullenix-v-luna.txt",
          "versionId": "ver_8b2e6d1f4a9c4e7b9d3a5f0c2e8b6d41",
          "unit": "chars",
          "start": 4120,
          "end": 5260
        }
      ]
    }
  ],
  "nextCursor": null,
  "execution": { "mode": "hybrid" },
  "timingMs": { "retrieval": 41, "total": 58 },
  "warnings": []
}

A result is a document of the dataset, with the same fields as a bucket result: its key, its versionId, and the spans that matched. The mode, the result type, the limit, the key scope, and the cursor work as in Search your objects. The CLI prints the key and the spans.

Read spans

The storage API and S3 tools cannot read a dataset document. Read its content with Read spans. Send the dataset id as target, and the spans exactly as search returned them. include works as for a bucket: text (the default), raw, and object, which returns the whole document.

cURL

curl --request POST \
  --url "https://api.beta.graphon.ai/v1/workspaces/$GRAPHON_WORKSPACE_ID/read-spans" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "target": "dstC4s3L4w0x1",
    "spans": [
      {
        "key": "scotus/2015/mullenix-v-luna.txt",
        "versionId": "ver_8b2e6d1f4a9c4e7b9d3a5f0c2e8b6d41",
        "unit": "chars",
        "start": 4120,
        "end": 5260
      }
    ],
    "include": ["text"]
  }'

A query reads only the newest version of each document. When Graphon changes a document, a span of the older version has the error not_found on its own result. Search again, and read the new span.

Answer a question

CLI

graphon ask dstC4s3L4w0x1 "Which cases overruled Chevron?"
graphon chat dstC4s3L4w0x1

cURL

curl --request POST \
  --url "https://api.beta.graphon.ai/v1/workspaces/$GRAPHON_WORKSPACE_ID/answer" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "target": "dstC4s3L4w0x1",
    "query": "Which cases overruled Chevron?"
  }'

Response

{
  "answer": "Loper Bright Enterprises v. Raimondo overruled Chevron in 2024 [[SRC:0001]].",
  "sources": [
    {
      "ref": "SRC:0001",
      "key": "scotus/2024/loper-bright-v-raimondo.txt",
      "versionId": "ver_5c7a1e9d3b6f4a2c8e0d4b7f1a3c9e52",
      "contentType": "text/plain",
      "score": 0.88,
      "cited": true,
      "span": {
        "key": "scotus/2024/loper-bright-v-raimondo.txt",
        "versionId": "ver_5c7a1e9d3b6f4a2c8e0d4b7f1a3c9e52",
        "unit": "chars",
        "start": 18402,
        "end": 18977
      }
    }
  ],
  "warnings": [],
  "imageDescription": null,
  "timingMs": { "total": 3870 }
}

Each [[SRC:0001]] marker matches the source whose ref is SRC:0001, as in Answer a question. To show the cited text, send the source's span to Read spans.

Research a dataset

CLI

graphon research start dstC4s3L4w0x1 \
  "How have the federal courts of appeals ruled on drone surveillance?" --watch

cURL

curl --request POST \
  --url "https://api.beta.graphon.ai/v1/workspaces/$GRAPHON_WORKSPACE_ID/research" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "target": "dstC4s3L4w0x1",
    "query": "How have the federal courts of appeals ruled on drone surveillance?"
  }'

The run belongs to your workspace, and its target is the dataset id. Follow it and read it as in Research a bucket. A run that started stays readable until its expiresAt, also when Graphon retires the dataset.

Query a dataset from an agent

The Graphon MCP server has list_datasets and get_dataset. The query tools take target: a bucket id, the exact name of a bucket, or a dataset id. They do not take a dataset slug, so a slug never matches a bucket of the same name. read_object with a dataset id returns an error that says to call read_spans. See the MCP tools.

Usage and errors

A dataset query counts toward your plan's queries per month, like a bucket query. A dataset counts toward no storage of your workspace.

ErrorWhat it means
400 invalid_requestThe target is not a bucket id or a dataset id. The message says: target must be a bucket id (bkt…) or a dataset id (dst…).
403 dataset_access_requiredThe dataset is paid, and your workspace has no access. details.target names the dataset.
404 not_foundThe dataset is a draft, retired, or unknown.
409 index_not_readyNo document of the dataset is ready yet. Retry after the Retry-After seconds.
503 temporarily_unavailableGraphon cannot serve the dataset right now. Retry after the Retry-After seconds.

403 response

HTTP/1.1 403 Forbidden
Content-Type: application/json
x-request-id: 2b7e9c41-5d3a-4f08-9c6e-1a8d0f4b7e25

{
  "error": {
    "code": "dataset_access_required",
    "message": "People index is a paid dataset. A workspace admin can get access.",
    "requestId": "2b7e9c41-5d3a-4f08-9c6e-1a8d0f4b7e25",
    "retryable": false,
    "details": { "target": "dstP3op1eIdx0" }
  }
}

A paid dataset

The catalog lists a paid dataset with its price, also before your workspace has access. To get access, contact Graphon.

Next

  1. Read every field in the List datasets reference.
  2. Search your own files in Search your objects.
Was this page helpful?
View as Markdown