Get briefs

Returns one durable research brief and all of its specialist child tasks, citations, unsupported claims, open questions, and attribution records.

GET /v1/agent/briefs/{id}

Agent → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/agent/briefs/{id}`
Method	`GET`
Operation	`get_agent_briefs_by_id`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Returns one durable research brief and all of its specialist child tasks, citations, unsupported claims, open questions, and attribution records.

Request

1 field.

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the brief handle (`brief_...`) from the path.

Response

Status	Body	Meaning
`200`	agent.BriefRecord	ok
`default`	problem-details	refused

200 body — 45 fields.

Field	In	Type	Always	Description
`attribution`	body	agent.BriefAttribution[]	—	Attribution records who did what across the lead and specialist agents.
`attribution[].agentId`	body	string	—	AgentID is the contributing agent's stable ID.
`attribution[].agentName`	body	string	—	AgentName is the contributing agent's handle.
`attribution[].citations`	body	string[]	—	Citations are the source citations contributed by this agent.
`attribution[].function`	body	string	—	Function is the studio function represented by the agent.
`attribution[].microUsd`	body	integer (int64)	—	MicroUSD is the spend attributed to this agent on the brief in integer micro-USD.
`attribution[].parentId`	body	string	—	ParentID is the manager agent ID this agent reports to.
`attribution[].role`	body	string	—	Role is "lead" or "specialist".
`attribution[].runId`	body	string	—	RunID is the agent_runs execution ID that produced this contribution.
`attribution[].summary`	body	string	—	Summary is a concise excerpt of what this agent produced.
`citations`	body	string[]	—	Citations are the deduplicated source citations across the specialist tasks and lead synthesis.
`createdAt`	body	integer (int64)	—	CreatedAt is when the brief was submitted, as Unix seconds.
`id`	body	string	—	ID is the stable brief handle (`brief_...`).
`leadAgent`	body	string	—	LeadAgent is the venture lead agent's handle.
`leadAgentId`	body	string	—	LeadAgentID is the venture lead agent's stable ID.
`leadRunId`	body	string	—	LeadRunID is the recorded run ID of the lead synthesis once completed.
`openQuestions`	body	string[]	—	OpenQuestions are the unresolved questions surfaced for domain review or follow-up.
`question`	body	string	—	Question is the nonconfidential research question assigned to the venture lead.
`rerunsPerformed`	body	integer (int64)	—	RerunsPerformed is how many failed specialist tasks were re-executed on the latest rerun.
`skippedCompleted`	body	integer (int64)	—	SkippedCompleted is how many already-completed specialist tasks were preserved without re-running on the latest rerun.
`status`	body	string	—	Status is the brief's lifecycle state: completed or partial_failure.
`synthesis`	body	string	—	Synthesis is the lead agent's integrated synthesis once all specialist child tasks succeed.
`tasks`	body	agent.BriefTask[]	—	Tasks are the durable specialist child tasks belonging to this brief.
`tasks[].agentId`	body	string	—	AgentID is the specialist agent's stable handle (`agent_...`).
`tasks[].agentName`	body	string	—	AgentName is the specialist agent's name in the organization.
`tasks[].attempts`	body	integer (int64)	—	Attempts counts how many times this specialist task has been executed.
`tasks[].briefId`	body	string	—	BriefID is the parent research brief identifier (`brief_...`).
`tasks[].citations`	body	string[]	—	Citations are the source references extracted from the specialist's output.
`tasks[].error`	body	string	—	Error records the failure reason when status is "error".
`tasks[].function`	body	string	—	Function is the studio function the specialist represents.
`tasks[].id`	body	string	—	ID is the stable task identifier (`task_...`).
`tasks[].lineage`	body	string[]	—	Lineage is the specialist's ancestor agent IDs, nearest first.
`tasks[].microUsd`	body	integer (int64)	—	MicroUSD is the cumulative spend of this child task in integer micro-USD.
`tasks[].output`	body	string	—	Output is the attributable text produced by the specialist when status is "done".
`tasks[].parentId`	body	string	—	ParentID is the manager agent ID in the specialist's lineage.
`tasks[].prompt`	body	string	—	Prompt is the specialist-scoped sub-brief dispatched to this agent.
`tasks[].runId`	body	string	—	RunID is the recorded agent_runs row ID for the latest execution attempt.
`tasks[].status`	body	string	—	Status is the durable task state: pending, done, or error.
`tasks[].unsupportedClaims`	body	string[]	—	UnsupportedClaims are the claims the specialist flagged as lacking primary evidence.
`tasks[].updatedAt`	body	integer (int64)	—	UpdatedAt is when the child task was last updated, as Unix seconds.
`title`	body	string	—	Title is the short headline of the research brief.
`totalMicroUsd`	body	integer (int64)	—	TotalMicroUSD is the total spend across all specialist tasks and the lead synthesis in integer micro-USD.
`unsupportedClaims`	body	string[]	—	UnsupportedClaims are the claims flagged as lacking primary empirical support.
`updatedAt`	body	integer (int64)	—	UpdatedAt is when the brief was last updated, as Unix seconds.
`venture`	body	string	—	Venture is the venture slug this research brief belongs to.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo agent briefs get <id>

.ts

.py

.go

.rs

.java

import { Configuration, AgentApi } from 'hanzoai';

const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getAgentBriefsById({ id: 'id' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentApi(client).get_agent_briefs_by_id(id='id')

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.AgentAPI.GetAgentBriefsById(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, agent_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = agent_api::get_agent_briefs_by_id(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new AgentApi(client).getAgentBriefsById();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl https://api.hanzo.ai/v1/agent/briefs/<id> \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches agent through the agent tool, which names its 51 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_agents"
         }
       }
     }'

Agent API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousList activity NextList briefs