Answer a question

Overview

Answer takes a question about one bucket and returns one written answer on the same call. Graphon finds the material, reads it, writes the answer, and marks every claim with the source it came from.

target names what to answer from: a bucket id (bkt…) or a dataset id (dst…). This guide asks a bucket. To ask a dataset that Graphon curates, read Query a dataset.

Use Answer when the reader wants the answer. Use Search when your application wants the material and will decide what to do with it. Use Research for a question that needs many reads, or for a complete list where a missed match is the failure.

The call usually answers in seconds. The call waits for the answer and returns 200. Like Search, Answer stores nothing: the answer comes back only on this call, and there is no id to read it again. If the call drops, ask again. A question that takes minutes belongs in Research, whose run stays readable after the call.

Before you start

The bucket needs indexing enabled and at least one object that finished indexing. Check it with graphon buckets index-status, as in Search your objects. A viewer key is enough.

Ask a question

graphon ask support-tickets "Why did checkout stall after the 3 October deploy?"
graphon chat support-tickets

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": "'"$GRAPHON_BUCKET_ID"'",
    "query": "Why did checkout stall after the 3 October deploy?",
    "history": []
  }'

{
  "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": 3,
        "end": 4
      }
    }
  ],
  "warnings": [],
  "imageDescription": null,
  "timingMs": { "total": 4120 }
}

Read the citations

Each [[SRC:0001]] marker in the answer matches the source whose ref is SRC:0001. The source carries the key, the version that was used, and the span inside it, so a link can open the file at its page or its time range. Pages count from 1, the same as a PDF viewer. A span holds no text: send the spans of an answer to Read spans in one call, as in Search objects. The default include text returns their words, and include raw returns the pages or the clip.

const CITATION = /\[\[(SRC:\d{4})\]\]/g;

// Each marker becomes a link to the source whose ref is the same text.
export function Answer({ answer, sources }: { answer: string; sources: Source[] }) {
  const parts = answer.split(CITATION);
  return (
    <p>
      {parts.map((part, index) =>
        index % 2 === 1 ? <Citation key={index} source={byRef(sources, part)} /> : part
      )}
    </p>
  );
}

Choose the sources and the style

sources sets which sources come back. all is the default: the cited sources first, then the ones that were only read. cited returns only the cited sources. none returns no sources, and the answer has no markers. A source whose object version was deleted keeps its place, with versionId and span null.

instructions set how the answer reads: its length, tone, format, or language. They replace only the default style rules. The source rules stay, and the citation rules follow sources. Send at most 8,000 characters. Start research takes instructions too, and research always cites its sources. Set instructions through the API or MCP: the app has no field for them.

{
  "target": "bktA1b2C3d4E5",
  "query": "Why did checkout stall after the 3 October deploy?",
  "instructions": "Answer in two short sentences, in French.",
  "sources": "none"
}

Hold a conversation

Graphon keeps no conversation. Your application owns the turns and sends them back with each question, oldest first, at most 32. A follow-up can then say "it" and the answer knows what that means.

{
  "target": "bktA1b2C3d4E5",
  "query": "What did the team do about it?",
  "history": [
    { "role": "user", "content": "Why did checkout stall after the 3 October deploy?" },
    { "role": "assistant", "content": "Release 4.18 raised checkout workers from 8 to 24..." }
  ]
}

From a terminal, graphon chat does this for you: it answers one question for each line of input and sends the earlier turns with each one.

Ask about a picture

Send a PNG, JPEG, or WebP of at most 4 MiB in image, as base64 with no data: prefix. An image question is premium and adds up to 45 seconds. Graphon keeps no copy.

The reply carries imageDescription, which says what the picture showed. Put that text in the next turn's history and the follow-up sees the picture without sending it again.

When there is no answer

answer is null when the bucket held nothing to answer from. The warning says why. Show the warning. Do not show an empty answer, and do not fill the gap from somewhere else.

Next

1. Run a long question in Research a bucket.
2. Read every field in the Answer a question reference.
3. Let a coding agent do this for you with the Graphon plugin.