v36

latestOpenAPI 3.1.0raw.githubusercontent.com2025-10-091882241.2 MB

agents

List Agents

Get a list of all agents.

get/v1/agents/

Query parameters

namestring nullable

Name of the agent

tagsstring[] nullable

List of tags to filter agents by

match_all_tagsboolean

If True, only returns agents that match ALL given tags. Otherwise, return agents that have ANY of the passed-in tags.

beforestring nullable

Cursor for pagination

afterstring nullable

Cursor for pagination

limitinteger nullable

Limit for pagination

query_textstring nullable

Search agents by name

project_idstring nullable

Search agents by project ID - this will default to your default project on cloud

template_idstring nullable

Search agents by template ID

base_template_idstring nullable

Search agents by base template ID

identity_idstring nullable

Search agents by identity ID

identifier_keysstring[] nullable

Search agents by identifier keys

include_relationshipsstring[] nullable

Specify which relational fields (e.g., 'tools', 'sources', 'memory') to include in the response. If not provided, all relationships are loaded by default. Using this can optimize performance by reducing unnecessary joins.

order'asc' | 'desc'

Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first

order_by'created_at' | 'last_run_completion'

Field to sort by

ascendingboolean

Whether to sort agents oldest to newest (True) or newest to oldest (False, default)

sort_bystring nullable

Field to sort by. Options: 'created_at' (default), 'last_run_completion'

Response

Successful Response

created_by_idstring nullable

The id of the user that made this object.

last_updated_by_idstring nullable

The id of the user that made this object.

created_atstring date-time nullable

The timestamp when the object was created.

updated_atstring date-time nullable

The timestamp when the object was last updated.

idstring required

The id of the agent. Assigned by the database.

namestring required

The name of the agent.

message_idsstring[] nullable

The ids of the messages in the agent's in-context memory.

systemstring required

The system prompt used by the agent.

Enum to represent the type of agent.

descriptionstring nullable

The description of the agent.

metadataobject nullable

The metadata of the agent.

tagsstring[] required

The tags associated with the agent.

project_idstring nullable

The id of the project the agent belongs to.

template_idstring nullable

The id of the template the agent belongs to.

base_template_idstring nullable

The base template id of the agent.

deployment_idstring nullable

The id of the deployment.

entity_idstring nullable

The id of the entity within the template.

identity_idsstring[]

The ids of the identities associated with this agent.

message_buffer_autoclearboolean

If set to True, the agent will not remember previous messages (though the agent will still retain state via core memory blocks and archival/recall memory). Not recommended unless you have an advanced use case.

enable_sleeptimeboolean nullable

If set to True, memory management will move to a background agent thread.

last_run_completionstring date-time nullable

The timestamp when the agent last completed a run.

last_run_duration_msinteger nullable

The duration in milliseconds of the agent's last run.

timezonestring nullable

The timezone of the agent (IANA format).

max_files_openinteger nullable

Maximum number of files that can be open at once for this agent. Setting this too high may exceed the context window, which will break the agent.

per_file_view_window_char_limitinteger nullable

The per-file view window character limit for this agent. Setting this too high may exceed the context window, which will break the agent.

hiddenboolean nullable

If set to True, the agent will be hidden.

Example response

[
  {
    "memory": {
      "blocks": [
        {
          "id": "block-123e4567-e89b-12d3-a456-426614174000"
        }
      ],
      "file_blocks": [
        {
          "id": "block-123e4567-e89b-12d3-a456-426614174000"
        }
      ]
    },
    "tools": [
      {
        "id": "tool-123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "sources": [
      {
        "id": "source-123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "tool_exec_environment_variables": [
      {
        "id": "agent-env-123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "secrets": [
      {
        "id": "agent-env-123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }
]