---
title: Answer a question
description: Answers a question about one target, with a citation marker for each source.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Answer a question

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

Answers a question about one target, with a citation marker for each source. The target is a bucket with indexing enabled, or a dataset from List datasets. Usually seconds. The call returns an answer or an error within about 2 minutes. The call waits for the answer and stores nothing. sources picks all, cited, or no sources. Scope the question with keys, keyPrefix, or a metadata filter. 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.
- `history` (object[] (optional)) — Earlier turns, oldest first. At most 32. 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.
- `sources` (string (optional)) — all: cited sources first, in the order the answer cites them, then the sources it only retrieved. cited: only the sources that the answer cites. none: no sources, and no [[SRC:0001]] markers in the answer. Defaults to all. One of: all, cited, none.

## Example request

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

## CLI

```bash
graphon ask support-tickets "Why did checkout stall?"
```

## Example response

```json
{
  "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
      }
    }
  ],
  "warnings": [],
  "imageDescription": null,
  "timingMs": {
    "total": 6412
  }
}
```

## Sitemap

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