Start 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.
/v1/workspaces/{workspaceId}/researchAuthentication
Send your Graphon API key with every request. The value is the whole API key that Graphon showed when you created it. See Authentication.
Authorization: Bearer <GRAPHON_API_KEY>Path parameters
workspaceIdstringThe workspace id.
Request body
targetstringWhat to query: a bucket id (bkt…) of this workspace with indexing enabled, or a dataset id (dst…) from List datasets.
querystringThe question to answer. It must contain text. At most 32,000 characters.
streamboolean (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.
historyobject[] (optional)Earlier turns, oldest first. At most 32. Stored with the run. Defaults to none.
Premium. A picture to ask about: PNG, JPEG, or WebP, at most 4 MiB. It adds up to 45 seconds. Graphon keeps no copy.
keysstring[] (optional)Use only these object keys. At most 50. With keyPrefix, an object must match both. Defaults to every object of the bucket.
keyPrefixstring (optional)Use only the objects whose key begins with this text, for example videos/2026/. Defaults to every object of the bucket.
filterobject (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.
instructionsstring (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.