Plan and run a query graph that returns cited, source-backed answers. Every claim carries the source ids it rests on.
Runs a query graph and returns the run plus its evidence packet.
Most search APIs return a list of links and stop. A graph run plans the research shape, executes the nodes, and returns an evidence packet — packet.claims[], where each claim carries the source_ids it rests on, resolving against packet.sources[]. An answer can be checked back to the pages that produced it rather than taken on trust.
The response also carries gaps[]: a branch that timed out or ran dry records the node, the query and the reason, so a thin result is visible instead of silently thin.
The endpoint takes query, not q. Credits are refunded in full if the engine is unreachable or errors, so a failed run costs nothing.
| Name | Type | Description |
|---|---|---|
queryrequired | string | Research query. 1-500 characters. |
engine | string | Engine id, or auto to let the planner choose. Defaults to auto. |
num | integer | Results per search node, 1-10. Defaults to 5. |
max_tokens | integer | Token ceiling for the evidence packet, 64-32000. |
deadline_ms | integer | Wall-clock ceiling for the run, 100-60000. |
max_nodes | integer | Maximum nodes the graph may contain, 1-32. Defaults to 12. |
fetch_top | integer | How many top results to fetch in full, 0-10. |
intent | string | Force an intent instead of detecting it. |
include_plan | boolean | Also return the graph that was executed. |
A dry run. Validates the graph and returns the graph, a cost estimate, the rationale for the shape chosen, and alternatives — without touching the network. Use it to size a run before paying for it.
Same request body as /v1/graph/search, minus include_plan. Costs 1 credit.
The packet is the point of a graph run. Its fields:
claims[] — each with id, text, and source_ids naming the sources it rests on.sources[] — the id/url pairs those ids resolve against.contradictions[] — sources that disagree.gaps[] — branches that did not complete.budget_tokens / used_tokens — what the packet was allowed and what it used.A claim whose source_ids cannot be resolved is a claim you cannot check. The session_handoff MCP tool reports exactly those as unresolvable_claim_ids, so a receiving agent knows what to re-verify rather than assuming every claim is sourced.
| Name | Type | Description |
|---|---|---|
graph_idrequired | string | Identifier for this run. |
statusrequired | string | ok, partial, or error. |
intentrequired | string | Intent the planner detected or was given. |
duration_msrequired | number | Wall-clock time for the run. |
engine_attributionrequired | object | How many search nodes each engine served. |
budgetrequired | object | Measured resource use: requests, bytes, nodes, tokens. |
packetrequired | object | The evidence packet: claims, sources, contradictions, gaps. |
gapsrequired | array | Branches that did not complete, with node, query and reason. |