Execuções de agente e uso

Cada execução de um agente sobre um e-mail, com tokens, custo e duração — mais as duas visões agregadas sobre os mesmos dados. Quatro tools, todas de leitura.

Veja o modelo AgentRun e o modelo Usage.

---

agent_runs_list

Leitura · escopo inbox/agent_runs · permissão agent-runs.list · GET /agent-runs

Lista execuções de agente com tokens, custo e duração. Paginado por cursor.

Parâmetro	Tipo	Descrição
cursor	string	Cursor opaco de uma página anterior.
limit	integer	Tamanho da página, padrão 25, máximo 100.
sort	string	Chaves de ordenação, prefixo - para descendente.
status	running | success | failed	Filtra por status da execução.
agent_id	string (uuid)	Apenas execuções deste agente.
email_id	string (uuid)	Apenas execuções sobre este e-mail.
inbox_id	string (uuid)	Apenas execuções de e-mail recebido nesta inbox.
llm_model	string	Filtra por modelo, no formato provider/model.
created_at_gte / created_at_lte	string	Intervalo ISO 8601 sobre created_at.
finished_at_gte / finished_at_lte	string	Intervalo ISO 8601 sobre finished_at.

agent_runs_get

Leitura · escopo inbox/agent_runs · permissão agent-runs.show · GET /agent-runs/{id}

Busca uma execução de agente, incluindo a versão de prompt com que ela rodou e o erro, quando falhou.

Parâmetro	Tipo	Descrição
id obrigatório	string (uuid)	Id da execução.

usage_summary

Leitura · escopo inbox/usage · permissão usage.show · GET /usage/summary

Uso agregado em um intervalo de datas: e-mails processados, execuções, tokens e custo. O padrão são os últimos 30 dias.

Parâmetro	Tipo	Descrição
from	string (YYYY-MM-DD)	Data inicial, inclusiva.
to	string (YYYY-MM-DD)	Data final, inclusiva.

usage_cost

Leitura · escopo inbox/usage · permissão usage.show · GET /usage/cost

Custo detalhado por modelo em um intervalo de datas. O padrão são os últimos 30 dias.

Parâmetro	Tipo	Descrição
from	string (YYYY-MM-DD)	Data inicial, inclusiva.
to	string (YYYY-MM-DD)	Data final, inclusiva.