Flow
Menu

Reference

List runs and what they cost

The list-agent-runs tool, and the REST call it is generated from.

RESTGET /api/v1/agent-runs
MCPlist-agent-runs

The newest matching runs, totals over every match, and with group_by the totals per value. Filters intersect. peak_context is the largest, every other counter a sum; unpriced counts runs with no cost_usd yet. A run on several tasks counts in each task or tag group. task with status=running lists the runs holding a task.

Parameters

  • projectquery · optional
  • taskquery · optional

    Runs that worked on this task.

  • upstream_ofquery · optional

    Runs that worked on this task or anything that blocks it, closed work included: the cost of a milestone.

  • tagquery · optional · string

    Runs that worked on a task with this tag.

  • modelquery · optional · string
  • agentquery · optional · string
  • parentquery · optional · string

    The children of this run.

  • byquery · optional · array

    Runs whose recording credential is: me (you alone, not your teams), a user_…, or a team_… (any member). Each row's by is that user_…, null on old runs. Your run limit: agent, status=running, by=me.

  • statusquery · optional · array
  • linkedquery · optional · boolean

    false: runs that worked on no task.

  • lingeringquery · optional · boolean

    true: still running though every task it worked on is closed.

  • sincequery · optional · string

    Started at or after.

  • untilquery · optional · string

    Started before.

  • group_byquery · optional · string

    One of: model, agent, status, project, task, tag.

  • limitquery · optional · integer

    Rows to return, default 20; 0 for totals alone.

Responses

200The runs, their totals and groups
400The request does not match the operation's schema
404No project or task by that id that you can reach

Generated from the spec this operation is implemented against, so the two names above cannot disagree with the surface a client sees.