List Agent Runs

Beta
GET/v1/ai/runs

This endpoint is idempotent. Learn more

Lists agent runs for your account, newest first.

The q parameter matches a run's ID, its status, or the ID of the agent that produced it.

Permissions requiredValues:agent_runs:read
The role behind your API key or agent must grant every one of these permissions.
cursoroptional string

Opaque cursor token identifying where the page of results starts.

Use the cursor value embedded in a previous response's next_page_url or previous_page_url to fetch the adjacent page. Omit to start from the first page.

limitoptional integer

Maximum number of results to return in a single page.

qoptional string

Free-text search term used to filter results.

Which fields are matched against the term varies by endpoint.

statusoptional string

Restricts results to runs in this status.

One of pending, running, awaiting_input, awaiting_approval, completed, failed, or cancelled.

agent_definition_idoptional string

Restricts results to runs of a single agent.

include[]optional arrayenumValues:triggered_bydefinitionactions

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of agent_run

Resources in this page.

idstring

Agent run ID.

objectstringenumValues:agent_run

Resource type identifier.

trigger_typestringenumValues:scheduledmanualevent

How this run was initiated.

  • scheduled: started by the agent's cron schedule.
  • event: started in response to a platform event.
  • manual: started by an explicit request; see triggered_by.
  • chat: started by a message in a conversation, with the agent's reply posted back into that conversation.
statusstringenumValues:pendingrunningcompleted

Current run status.

  • pending: queued but not yet started.
  • running: currently executing.
  • awaiting_input: paused, waiting for user input before continuing.
  • awaiting_approval: paused, waiting for a pending action to be approved.
  • completed: finished successfully.
  • failed: stopped after an error; see error_message.
  • cancelled: stopped before completion by a user.
definitionagent_definitionExpandablenullable

The agent definition this run executes.

idstring

Agent definition ID.

objectstringenumValues:agent_definition

Resource type identifier.

definition_typestringenumValues:systemcustom

Whether the agent is provided by Augno or created in this account.

  • system: provided by Augno; cannot be edited or deleted.
  • custom: created by a user in this account.
category_codestring

Category grouping for the agent (e.g. order_processing), used to organize agents in the UI.

trigger_typestringenumValues:scheduledmanualevent

How runs of this agent are initiated.

  • scheduled: runs on a cron schedule (see config.trigger_config.cron_schedule).
  • event: runs in response to platform events (see config.trigger_config.event_filters).
  • manual: runs only when explicitly invoked.
  • chat: runs in response to a chat message; the run is linked to a conversation and posts its reply back into it.
namestring

Human-readable name of the agent.

slugstring

URL-friendly identifier for the agent.

Unique within the account.

descriptionstringnullable

Description of what the agent does.

editabilitystringenumValues:editableread_only

Whether this agent definition can be edited.

Always read_only for system definitions.

statusstringenumValues:activeinactive

Whether this agent is enabled for the current account.

Activation is per-account: a system agent shared across accounts can be active for one account and inactive for another. An inactive agent cannot be triggered.

roleroleExpandablenullable

Role defining the permissions the agent operates with.

The agent acts as its own actor, and everything it does is authorized against this role — it can never reach data or actions the role does not grant. An agent with no role cannot execute: its runs fail immediately.

idstring

Role ID.

objectstringenumValues:role

Resource type identifier.

namestring

Display name of the role.

Unique within the account.

typestringenumValues:adminuserscanner

The kind of role.

The type gates behavior that individual permissions do not cover, and some actions are reserved for a single role type.

  • admin: full administrative access. Sensitive areas such as API keys, billing, and third-party integrations are restricted to admins no matter what permissions another role holds.
  • user: a custom role tailored to a specific need, with its permissions defined explicitly. Roles created through the API always have this type.
  • scanner: the role used by shop-floor scanning stations, assigned automatically when a scanning-station user is created.
  • sales_rep: a role for sales representatives. Order analytics are scoped to the rep's own orders.
  • agent: a role assigned to an automated agent rather than a person.
ownerownernullable

Provenance of this role.

System-owned roles are platform-provided defaults shared across all accounts and cannot be updated or deleted; account-owned roles are custom to your account.

Always returned as null in this endpoint.
permissionsarray of stringnullable

Permissions granted by this role, in {permission}:{action} format, such as customers:read.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

configagent_definition_configExpandablenullable

Agent-level configuration controlling LLM behavior and trigger settings.

objectstringenumValues:agent_definition_config

Resource type identifier.

system_promptstringnullable

Standing instructions that define the agent's role and how it should behave on every run.

tierstringnullableenumValues:frontierhighbalanced

Intelligence and cost tier for the agent's reasoning.

Selects how capable and expensive a model the agent uses without pinning a specific model; higher tiers reason better but cost more. Each tier resolves to an ordered chain of equivalent models, so a run automatically fails over to another provider's model if the preferred one is unavailable.

  • frontier: the most capable tier, for multi-step planning, ambiguous agent work, and hard coding or architecture tasks.
  • high: for normal planning, code edits, synthesis, and customer-facing reasoning.
  • balanced: for research, summarization, classification, structured extraction, and light tool use.
  • cheap: for simple transforms, validation, formatting, and routing.
  • legacy: older-generation models kept for compatibility and regression comparison; avoid unless you specifically need them.

Leaving the tier unset picks one from how the agent is triggered: chat and manual runs use high, while scheduled and event-driven runs use balanced so background work stays cheap.

temperaturenumbernullable

LLM sampling temperature between 0 and 1.

Lower values make the agent's output more repeatable and literal; higher values make it more varied.

trigger_configtrigger_confignullable

Trigger-specific configuration.

Shape depends on the agent's trigger_type.

Always returned as null in this endpoint.
endpoint_tool_slugsarray of string

API-endpoint tools the agent may discover and use, by slug (e.g. create_account_group).

These correspond to tools listed by the List Tools endpoint with category api_endpoint. A single entry * grants the entire endpoint-tool catalog.

endpoint_tool_reviewobject

Per-endpoint-tool human-review overrides, keyed by tool slug.

When an entry is true, the run pauses in awaiting_approval each time the agent calls that endpoint-tool until it is approved via the Continue Agent Run endpoint. Slugs absent from the map do not require review.

toolslistExpandablenullable

Tools attached to this agent.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of agent_definition_tool

Resources in this page.

idstring

Agent definition tool ID.

objectstringenumValues:agent_definition_tool

Resource type identifier.

toolavailable_tool

Attached tool.

Always returned as null in this endpoint.
review_requirementstringenumValues:not_requiredrequired

Whether calls to this tool must be approved by a user before they execute.

When required, the run pauses in the awaiting_approval status each time the agent invokes this tool; approve or allow the tool via the Continue Agent Run endpoint to proceed. A tool whose mutating flag is true still pauses for approval even when this is not_required.

configobjectnullable

Instance-specific configuration for this tool.

Must conform to the tool's config_schema.

Encoded as a JSON value (object, array, string, number, boolean, or null), not a JSON-encoded string.

sort_orderinteger

Sort order within the agent.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

inputobjectnullable

Input provided to the agent at the start of the run.

The shape depends on what started the run; a manually triggered run records {"message": "<your input>"}.

Encoded as a JSON value (object, array, string, number, boolean, or null), not a JSON-encoded string.

outputobjectnullable

Final output produced by the agent.

Present once the agent has produced a result, including on a run that paused for more input or was cancelled part-way through. A run that has not produced one yet carries an empty object.

Encoded as a JSON value (object, array, string, number, boolean, or null), not a JSON-encoded string.

error_messagestringnullable

Error message if the run failed.

triggered_byactorExpandablenullable

Actor that triggered this run.

Set only for runs started through the Trigger Agent Run endpoint; runs started by a schedule, a platform event, or a chat message have no triggering actor.

idstring

Unique identifier of the actor.

objectstringenumValues:actor

Resource type identifier.

typestringenumValues:userapi_keyagent

Actor type.

  • user: a human user account.
  • api_key: a programmatic caller authenticating with an API key.
  • agent: an automated agent acting on the account's behalf.
  • group: a shared group identity, such as a "Customer Service" persona, rather than a single individual.
namestringnullable

The actor's display name.

handlestringnullable

Human-readable handle identifying the actor.

  • For user actors: the user's email address.
  • For api_key actors: the redacted key value.

Other actor types carry no handle.

avatar_urlstringnullable

URL of the actor's profile photo, if one is set.

Only populated for user actors.

rolerolenullable

The role the actor holds in the account, which determines what it is permitted to do.

Always returned as null in this endpoint.
started_atstring (date-time)nullable

When the run started executing.

completed_atstring (date-time)nullable

When the run completed.

duration_msintegernullable

How long the run took, in milliseconds.

actionslistExpandablenullable

Tool invocations the agent made during this run.

Includes calls that were held for human review and never executed, so an entry here does not by itself mean the tool ran.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of agent_action

Resources in this page.

idstring

Agent action ID.

objectstringenumValues:agent_action

Resource type identifier.

toolstringenumValues:create_artifactread_docfetch_url

The tool the agent invoked for this action.

  • create_artifact: create an artifact such as a report, document, or data export.
  • read_doc: read Augno documentation pages.
  • fetch_url: fetch content from a public URL.
  • draft_reply: propose a reply to the case's external party as a draft held for human approval (not sent).
  • send_email: send an email reply through the conversation's bound inbox.
statusstringenumValues:pending_reviewauto_approvedapproved

Current action status.

  • pending_review: awaiting human review before it can execute.
  • auto_approved: automatically approved by policy.
  • approved: manually approved by a user.
  • rejected: rejected by a user; will not execute.
  • executed: successfully executed.
  • failed: errored during execution; see error_message.
labelstringnullable

Short human-readable label summarizing the action.

descriptionstringnullable

Longer description of what the action does.

runagent_runnullable

Agent run this action belongs to.

Always returned as null in this endpoint.
inputobjectnullable

Arguments passed to the tool, as JSON.

Shape depends on tool.

Encoded as a JSON value (object, array, string, number, boolean, or null), not a JSON-encoded string.

outputobjectnullable

Result returned by the tool, as JSON.

The shape depends on tool. An action that has not executed — because it is still waiting on a review decision, or was rejected — carries {}.

Encoded as a JSON value (object, array, string, number, boolean, or null), not a JSON-encoded string.

error_messagestringnullable

Error message if the action failed.

entityentitynullable

The resource this action operated on, when the tool targets a specific entity such as a customer or product.

Always returned as null in this endpoint.
review_requirementstringenumValues:not_requiredrequired

Whether a person must approve this action before it takes effect.

Fixed when the action is recorded, from the agent's review setting for that tool; tools that take an externally visible action, such as send_email, always require review and cannot be exempted. When review is required the action starts in pending_review and stays there until someone approves or rejects it; otherwise it is auto_approved.

reviewed_atstring (date-time)nullable

When a human review decision was recorded for the action.

reviewed_byactornullable

Who reviewed the action.

Always returned as null in this endpoint.
executed_atstring (date-time)nullable

When the action was executed.

created_atstring (date-time)

When this action was created.

updated_atstring (date-time)

When this action was last updated.

stepslistnullable

Step-by-step timeline of what happened during the run.

Ordered by sequence, oldest first.

created_atstring (date-time)

When this run was created.

updated_atstring (date-time)

When this run was last updated.

Responses

200

Successful response for List Agent Runs