---
title: Start research
description: Starts a premium research run on one target: a bucket with indexing enabled, or a dataset from List datasets.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Start research

`POST /v1/workspaces/{workspaceId}/research`

Starts a premium research run on one target: a bucket with indexing enabled, or a dataset from List datasets. Use it when one search is not enough, and the answer needs several steps. Minutes. At most 600 seconds. It returns at once with status running. It never waits for the answer: follow the run with Research events, and read it with Get research until expiresAt. The run belongs to the calling workspace. Scope the question with keys, keyPrefix, or a metadata filter. Ask a question that one pass can answer with Answer a question. Requires the viewer role. An image is a premium feature.

## 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.
- `query` (string) — The question to answer. It must contain text. At most 32,000 characters.
- `stream` (boolean (optional)) — false: 202 with the running run at once. true: 200 text/event-stream, the events of the run until it ends, as Run events sends them. Either way the Location header names the run. Defaults to false.
- `history` (object[] (optional)) — Earlier turns, oldest first. At most 32. Stored with the run. Defaults to none.
- `image` (object (optional)) — Premium. A picture to ask about: PNG, JPEG, or WebP, at most 4 MiB. It adds up to 45 seconds. Graphon keeps no copy.
- `keys` (string[] (optional)) — Use only these object keys. At most 50. With keyPrefix, an object must match both. Defaults to every object of the bucket.
- `keyPrefix` (string (optional)) — Use only the objects whose key begins with this text, for example videos/2026/. Defaults to every object of the bucket.
- `filter` (object (optional)) — Use only the objects whose metadata matches. A clause is { field, op, value } on a metadata field that the bucket lists. text takes every operator. number and time take eq, neq, gt, gte, lt, and lte. bool takes eq and neq. A value is text, a number or a decimal string, an RFC 3339 time, or true or false; in takes an array of 1 to 100 values. and, or, and not combine clauses, at most 4 levels deep and 32 clauses in all. neq and not keep objects that have no value for the field. With keys or keyPrefix, an object must match all of them. A field that is still indexing after a change fails with metadata_field_indexing.
- `instructions` (string (optional)) — How to write the answer, for example its length, tone, format, or language. They replace only the default style rules. They do not change the citations. At most 8,000 characters. A blank value is the same as none. Defaults to none.

## Example request

```bash
curl \
  --url "https://api.beta.graphon.ai/v1/workspaces/wspq7ws2np5l8z4/research" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"target":"bktA1b2C3d4E5","query":"Why did checkout stall after the 3 October deploy?","stream":false,"history":[]}'
```

## CLI

```bash
graphon research start support-tickets "Every checkout timeout" --mode recall
```

## Example response

```json
{
  "research": {
    "id": "rscR7tY2kL9mP",
    "workspaceId": "wsp4k9m2x7q1z8r",
    "target": "bktA1b2C3d4E5",
    "status": "succeeded",
    "query": "Why did checkout stall after the 3 October deploy?",
    "history": [],
    "keys": [],
    "keyPrefix": null,
    "filter": null,
    "answer": "Release 4.18 raised checkout workers from 8 to 24 but left the database pool at 200 [[SRC:0001]].",
    "sources": [
      {
        "ref": "SRC:0001",
        "key": "incidents/2026-10-03-checkout.pdf",
        "versionId": "ver_3f9c2a7d1e4b4c8a9f0d6b2e5a1c7d3f",
        "contentType": "application/pdf",
        "score": 0.86,
        "cited": true,
        "span": {
          "key": "incidents/2026-10-03-checkout.pdf",
          "versionId": "ver_3f9c2a7d1e4b4c8a9f0d6b2e5a1c7d3f",
          "unit": "pages",
          "start": 2,
          "end": 3
        }
      }
    ],
    "sourcesNextCursor": null,
    "warnings": [],
    "error": null,
    "imageDescription": null,
    "createdBy": {
      "userId": null,
      "apiKeyId": "apkH3sK8pW2xQ"
    },
    "createdAt": "2026-10-12T09:00:00.000Z",
    "completedAt": "2026-10-12T09:03:42.210Z",
    "expiresAt": "2026-10-19T09:03:42.210Z"
  }
}
```

## Sitemap

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