List briefs

Returns every durable research brief recorded in the caller's organization, newest first.

GET /v1/agent/briefs

Agent → · All API references → · Get started →

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

Returns every durable research brief recorded in the caller's organization, newest first.

Request

GET /v1/agent/briefs takes no parameters and no body — the credential is the whole request.

Response

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

200 body — 46 fields.

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

.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.getAgentBriefs();

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()

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

resp, _, err := client.AgentAPI.GetAgentBriefs(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(&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).getAgentBriefs();

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 \
  -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.

PreviousGet briefs NextGet builds