> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt > Use this file to discover all available pages before exploring further. # List executions > List executions with filtering and pagination ## OpenAPI ````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /agents/v2/executions openapi: 3.1.0 info: title: Agent Service version: v1 servers: - url: https://odyssey.asteroid.ai security: - ApiKeyAuth: [] tags: - name: Agents - name: Environments - name: Schedules - name: Execution - name: Files - name: Profiles - name: Profile Groups - name: Agent Profiles - name: Agent Profile Pools - name: Workflows - name: Execution Batches - name: Scheduled Executions - name: Schema - name: Documentation - name: Context - name: Admin Customer Activity - name: Reference - name: Workflow Tags - name: Secrets - name: Vault - name: Insights - name: Workflow Versions paths: /agents/v2/executions: get: tags: - Execution summary: List executions description: List executions with filtering and pagination operationId: Executions_list parameters: - description: Optional organization ID filter (required for customer queries) explode: false in: query name: organizationId schema: $ref: '#/components/schemas/Common.uuid' - $ref: '#/components/parameters/Common.Pagination.pageSize' - $ref: '#/components/parameters/Common.Pagination.page' - $ref: '#/components/parameters/Agents.Execution.Search.executionId' - $ref: '#/components/parameters/Agents.Execution.Search.agentId' - $ref: '#/components/parameters/Agents.Execution.Search.agentProfileIds' - $ref: '#/components/parameters/Agents.Execution.Search.status' - $ref: '#/components/parameters/Agents.Execution.Search.createdAfter' - $ref: '#/components/parameters/Agents.Execution.Search.createdBefore' - $ref: '#/components/parameters/Agents.Execution.Search.humanLabels' - $ref: '#/components/parameters/Agents.Execution.Search.outcomeLabel' - $ref: '#/components/parameters/Agents.Execution.Search.metadataKey' - $ref: '#/components/parameters/Agents.Execution.Search.metadataValue' - $ref: '#/components/parameters/Agents.Execution.Search.inputsKey' - $ref: '#/components/parameters/Agents.Execution.Search.inputsValue' - $ref: '#/components/parameters/Agents.Execution.Search.workflowVersion' - $ref: '#/components/parameters/Agents.Execution.Search.hasScriptFailures' - $ref: '#/components/parameters/Agents.Execution.Search.triggerSource' - $ref: '#/components/parameters/Agents.Execution.Search.phase' - explode: false in: query name: sortField schema: $ref: '#/components/schemas/Agents.Execution.SortField' - explode: false in: query name: sortDirection schema: $ref: '#/components/schemas/Common.SortDirection' - $ref: '#/components/parameters/Agents.Execution.WorkflowFilter' - $ref: >- #/components/parameters/Agents.Execution.FilterShorthands.createdWithin - $ref: '#/components/parameters/Agents.Execution.FilterShorthands.metadata' - description: >- Sort shorthand as field:direction, e.g. created_at:desc. Fields: created_at, status, started_at. Cannot be combined with sortField or sortDirection explode: false in: query name: sort schema: pattern: ^(created_at|status|started_at):(asc|desc)$ type: string - $ref: '#/components/parameters/Agents.Execution.ProfileFilter' responses: '200': content: application/json: schema: properties: items: items: $ref: '#/components/schemas/Agents.Execution.ListItem' type: array page: format: int64 type: integer pageSize: format: int64 type: integer total: format: int64 type: integer required: - items - page - pageSize - total type: object description: The request has succeeded. '400': content: application/json: schema: $ref: '#/components/schemas/Common.BadRequestErrorBody' description: The server could not understand the request due to invalid syntax. '401': content: application/json: schema: $ref: '#/components/schemas/Common.UnauthorizedErrorBody' description: Access is unauthorized. '403': content: application/json: schema: $ref: '#/components/schemas/Common.ForbiddenErrorBody' description: Access is forbidden. '404': content: application/json: schema: $ref: '#/components/schemas/Common.NotFoundErrorBody' description: The server cannot find the requested resource. '500': content: application/json: schema: $ref: '#/components/schemas/Common.InternalServerErrorBody' description: Server error components: schemas: Common.uuid: format: uuid type: string Agents.Execution.SortField: description: Fields that can be used for sorting executions enum: - created_at - status - started_at type: string Common.SortDirection: enum: - asc - desc type: string x-go-type: sort.Direction x-go-type-import: name: sort path: github.com/asteroidai/agents/go/common/sort Agents.Execution.ListItem: description: Represents a single execution in a list view properties: agentId: allOf: - $ref: '#/components/schemas/Common.uuid' deprecated: true description: 'Deprecated: use workflowId. The ID of the workflow that was executed' x-hidden: true agentName: deprecated: true description: 'Deprecated: use workflowName. The workflow display name' type: string agentProfileId: allOf: - $ref: '#/components/schemas/Common.uuid' deprecated: true description: >- Deprecated: use profileId. The ID of the agent profile used for this execution (if any) x-hidden: true agentProfileName: deprecated: true description: >- Deprecated: use profileName. The name of the agent profile used for this execution (if any) type: string x-hidden: true browserLiveViewUrl: deprecated: true description: 'Deprecated: Use ''liveViewUrl'' instead.' type: string browserRecordingUrl: deprecated: true description: 'Deprecated: Use ''recordingUrl'' instead.' type: string comments: items: $ref: '#/components/schemas/Agents.Execution.Comment' type: array createdAt: format: date-time type: string duration: description: Execution duration in seconds (only present for terminal executions) format: double type: number executionOptions: allOf: - $ref: '#/components/schemas/Agents.Agent.ExecutionOptions' description: Per-execution runtime options (e.g. variant key) executionResult: $ref: '#/components/schemas/Agents.Execution.ExecutionResult' hasBeenRerun: type: boolean humanLabels: items: $ref: '#/components/schemas/Agents.Execution.HumanLabel' type: array id: $ref: '#/components/schemas/Common.uuid' inputs: type: object unevaluatedProperties: {} liveViewUrl: description: >- Live view URL for debugging (if an environment is active and execution is running) type: string metadata: type: object unevaluatedProperties: type: string organizationId: $ref: '#/components/schemas/Common.uuid' parentExecutionId: allOf: - $ref: '#/components/schemas/Common.uuid' description: ID of the execution this was rerun from, if applicable platformUrl: description: Deep link to this execution in the Asteroid platform UI type: string profileId: $ref: '#/components/schemas/Common.uuid' profileName: type: string purgedAt: description: >- When the retention purge removed this execution's data. Inputs, activities, files and recordings are gone; the row is a tombstone. format: date-time type: string x-hidden: true recordingUrl: description: >- Recording URL for playback (if an environment was used and execution is terminal) type: string scriptFailures: description: >- Script failures recorded for this execution (omitted when none occurred) items: $ref: '#/components/schemas/Agents.Execution.ScriptFailure' type: array startedAt: description: >- When the execution actually started running; absent while queued. createdAt means "enqueued at" for executions that waited in the queue. format: date-time type: string status: $ref: '#/components/schemas/Agents.Execution.Status' terminalAt: format: date-time type: string triggerContext: allOf: - $ref: '#/components/schemas/Agents.Execution.TriggerContext' description: >- Context about how and by whom this execution was triggered (discriminated by source) workflowId: $ref: '#/components/schemas/Common.uuid' workflowName: type: string workflowVersionId: $ref: '#/components/schemas/Common.uuid' required: - id - agentId - workflowId - workflowVersionId - status - createdAt - organizationId - agentName - workflowName - humanLabels - comments - hasBeenRerun type: object Common.BadRequestErrorBody: properties: code: enum: - 400 type: number x-enum-varnames: - BadRequest detail: description: Explanation of this occurrence. Same text as message type: string errors: description: The parameters that failed validation, when known items: $ref: '#/components/schemas/Common.FieldError' type: array instance: description: The request path that produced the problem type: string message: type: string status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.UnauthorizedErrorBody: properties: code: enum: - 401 type: number x-enum-varnames: - Unauthorized detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.ForbiddenErrorBody: properties: capability: description: The missing capability key, when reason is capability_required type: string code: enum: - 403 type: number x-enum-varnames: - Forbidden detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string reason: allOf: - $ref: '#/components/schemas/Common.ForbiddenReason' description: Why the request was refused, when the client can act on it status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.NotFoundErrorBody: properties: code: enum: - 404 type: number x-enum-varnames: - NotFound detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.InternalServerErrorBody: properties: code: enum: - 500 type: number x-enum-varnames: - InternalServerError detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Agents.Execution.Status: enum: - queued - starting - running - paused - awaiting_confirmation - completed - cancelled - failed - paused_by_agent type: string Agents.Execution.Phase: description: >- Execution lifecycle phase, derived from status. Every status belongs to exactly one phase. enum: - pending - active - terminal type: string Common.RelativeDuration: description: >- A span of time: number-unit pairs with units w, d, h, m, longest first, each at most once, e.g. 30m, 24h, 7d, 2w, 1d12h. A day is 24 hours pattern: >- ^([0-9]+w([0-9]+d)?([0-9]+h)?([0-9]+m)?|[0-9]+d([0-9]+h)?([0-9]+m)?|[0-9]+h([0-9]+m)?|[0-9]+m)$ type: string Agents.Execution.Comment: description: User comment on an execution properties: content: type: string createdAt: format: date-time type: string executionId: $ref: '#/components/schemas/Common.uuid' id: $ref: '#/components/schemas/Common.uuid' public: type: boolean updatedAt: format: date-time type: string userId: allOf: - $ref: '#/components/schemas/Common.uuid' description: User who created the comment required: - id - executionId - userId - content - public - createdAt type: object Agents.Agent.ExecutionOptions: description: Per-execution runtime options. properties: softTimeoutMins: description: >- Soft timeout in minutes. When the execution has been running longer than this value, a message is injected on every subsequent step urging the agent to wrap up and produce output. Must be greater than 0 and less than the agent's hard timeout (max_timeout_mins). minimum: 1 type: integer variantKey: description: >- Identifies which variant this execution is for, scoping its shared files and scripts to a per-variant subdirectory under each node's shared folder. It does not change which workflow or version runs. Normalised to a filesystem-safe slug by the server. Requires the workflow to have `variant_mode` enabled, and a variant-mode workflow requires it on every execution. type: string type: object Agents.Execution.ExecutionResult: description: Execution result containing outcome, reasoning, and result data properties: createdAt: format: date-time type: string executionId: $ref: '#/components/schemas/Common.uuid' id: $ref: '#/components/schemas/Common.uuid' outcome: description: Outcome of the execution (success or failure) type: string reasoning: type: string result: {} required: - id - executionId - outcome - reasoning - result - createdAt type: object Agents.Execution.HumanLabel: description: Human-applied label for categorizing executions properties: color: description: 'Hex color code for the label (e.g., #FF5733)' type: string createdAt: format: date-time type: string id: $ref: '#/components/schemas/Common.uuid' name: type: string organizationId: $ref: '#/components/schemas/Common.uuid' required: - id - organizationId - name - color - createdAt type: object Agents.Execution.ScriptFailure: description: A single failed run of a scripted iris node's script properties: actionId: description: Identifier correlating this failure to its activity event type: string error: type: string failedLine: description: 1-based line number where the script failed, if known format: int32 type: integer nodeId: type: string nodeName: type: string occurredAt: format: date-time type: string scriptFilepath: description: Relative path of the script file that failed type: string step: description: Execution step (iteration) at which the failure occurred format: int32 type: integer required: - occurredAt type: object Agents.Execution.TriggerContext: description: Discriminated union of trigger contexts (discriminated by source) discriminator: mapping: api: '#/components/schemas/Agents.Execution.APITriggerContext' schedule: '#/components/schemas/Agents.Execution.ScheduleTriggerContext' ui: '#/components/schemas/Agents.Execution.UITriggerContext' warmup: '#/components/schemas/Agents.Execution.WarmupTriggerContext' propertyName: source oneOf: - $ref: '#/components/schemas/Agents.Execution.APITriggerContext' - $ref: '#/components/schemas/Agents.Execution.UITriggerContext' - $ref: '#/components/schemas/Agents.Execution.ScheduleTriggerContext' - $ref: '#/components/schemas/Agents.Execution.WarmupTriggerContext' type: object Common.FieldError: description: A problem with one request parameter properties: detail: description: What is wrong with it type: string parameter: description: The query or path parameter name type: string required: - parameter - detail type: object Common.ForbiddenReason: enum: - capability_required type: string Agents.Execution.APITriggerContext: description: API-triggered execution context properties: actor: allOf: - $ref: '#/components/schemas/Common.Actor' description: >- Who started the execution. For an org key, read this and not `runner`: an org key has no user. apiKey: allOf: - $ref: '#/components/schemas/Agents.Execution.APIKeyRef' description: >- API key used for authentication (may be hidden for privacy when admin-triggered) runner: $ref: '#/components/schemas/Agents.Execution.TriggerRunner' source: enum: - api type: string required: - source - runner type: object Agents.Execution.ScheduleTriggerContext: description: Schedule-triggered execution context properties: schedule: $ref: '#/components/schemas/Agents.Execution.ScheduleRef' source: enum: - schedule type: string required: - source - schedule type: object Agents.Execution.UITriggerContext: description: UI-triggered execution context properties: actor: allOf: - $ref: '#/components/schemas/Common.Actor' description: Who started the execution. runner: $ref: '#/components/schemas/Agents.Execution.TriggerRunner' source: enum: - ui type: string required: - source - runner type: object Agents.Execution.WarmupTriggerContext: description: >- Warmup-triggered execution context: launched by a warm pool's replenisher properties: source: enum: - warmup type: string warmPoolId: allOf: - $ref: '#/components/schemas/Common.uuid' description: Warm pool whose replenisher launched the execution required: - source - warmPoolId type: object Common.Actor: description: >- Who did something: a person, an API key or one of Asteroid's services. Absent on a record made before actors were stored, on one a system job made, and when the caller may not see who it was. properties: id: description: The person's id, the key's id, or the service's name type: string kind: $ref: '#/components/schemas/Common.ActorKind' required: - kind - id type: object Agents.Execution.APIKeyRef: description: API key reference used for authentication properties: id: $ref: '#/components/schemas/Common.uuid' name: type: string required: - id - name type: object Agents.Execution.TriggerRunner: description: Runner information - who triggered the execution properties: email: type: string isAdmin: description: Whether the user is an admin (may be hidden for privacy) type: boolean userId: $ref: '#/components/schemas/Common.uuid' required: - userId - email type: object Agents.Execution.ScheduleRef: description: Schedule reference for schedule-triggered executions properties: cronExpression: description: Cron expression of the schedule type: string id: $ref: '#/components/schemas/Common.uuid' required: - id - cronExpression type: object Common.ActorKind: description: The kind of caller that did something enum: - person - api_key - service type: string parameters: Common.Pagination.pageSize: explode: false in: query name: pageSize schema: default: 50 format: int32 type: integer Common.Pagination.page: explode: false in: query name: page schema: default: 1 format: int32 type: integer Agents.Execution.Search.executionId: description: Search by execution ID (partial, case-insensitive match) explode: false in: query name: executionId schema: type: string Agents.Execution.Search.agentId: deprecated: true description: 'Deprecated: use workflowId. Filter by workflow ID' explode: false in: query name: agentId schema: $ref: '#/components/schemas/Common.uuid' x-hidden: true x-hidden: true Agents.Execution.Search.agentProfileIds: deprecated: true description: 'Deprecated: use profileIds. Filter by agent profile IDs' in: query name: agentProfileIds schema: items: $ref: '#/components/schemas/Common.uuid' type: array x-hidden: true x-hidden: true Agents.Execution.Search.status: description: >- Filter by execution status (can specify multiple, there is an 'OR' condition applied to these) in: query name: status schema: items: $ref: '#/components/schemas/Agents.Execution.Status' type: array Agents.Execution.Search.createdAfter: in: query name: createdAfter schema: format: date-time type: string Agents.Execution.Search.createdBefore: in: query name: createdBefore schema: format: date-time type: string Agents.Execution.Search.humanLabels: description: >- Filter by human labels (can specify multiple label IDs, there is an 'OR' condition applied to these) in: query name: humanLabels schema: items: $ref: '#/components/schemas/Common.uuid' type: array Agents.Execution.Search.outcomeLabel: description: Filter by execution result outcome (partial, case-insensitive match) in: query name: outcomeLabel schema: type: string Agents.Execution.Search.metadataKey: description: Filter by metadata key - must be used together with metadataValue explode: false in: query name: metadataKey schema: type: string Agents.Execution.Search.metadataValue: description: Filter by metadata value - must be used together with metadataKey in: query name: metadataValue schema: type: string Agents.Execution.Search.inputsKey: description: Filter by input variable key - must be used together with inputsValue explode: false in: query name: inputsKey schema: type: string Agents.Execution.Search.inputsValue: description: >- Filter by input variable value (partial, case-insensitive match) - must be used together with inputsKey in: query name: inputsValue schema: type: string Agents.Execution.Search.workflowVersion: explode: false in: query name: workflowVersion schema: type: integer Agents.Execution.Search.hasScriptFailures: explode: false in: query name: hasScriptFailures schema: type: boolean Agents.Execution.Search.triggerSource: description: >- Filter by how the execution was triggered (can specify multiple, there is an 'OR' condition applied to these) in: query name: triggerSource schema: items: enum: - api - ui - schedule - warmup type: string type: array Agents.Execution.Search.phase: description: >- Filter by lifecycle phase, derived from status (can specify multiple, OR across values). Composes with the status filter as AND. pending = queued; active = starting, running, awaiting_confirmation, paused, paused_by_agent; terminal = completed, cancelled, failed. in: query name: phase schema: items: $ref: '#/components/schemas/Agents.Execution.Phase' type: array Agents.Execution.WorkflowFilter: explode: false in: query name: workflowId schema: $ref: '#/components/schemas/Common.uuid' Agents.Execution.FilterShorthands.createdWithin: description: >- Filter executions created within this long before now: number-unit pairs with units w, d, h, m, longest first, e.g. 30m, 24h, 7d, 1d12h. Maximum 10 years. Cannot be combined with createdAfter explode: false in: query name: createdWithin schema: $ref: '#/components/schemas/Common.RelativeDuration' Agents.Execution.FilterShorthands.metadata: description: >- Filter by metadata key=value pairs. Repeat the parameter for several pairs; every pair must match in: query name: metadata schema: items: type: string type: array Agents.Execution.ProfileFilter: description: >- Filter by login profile IDs (can specify multiple, there is an 'OR' condition applied to these) in: query name: profileIds schema: items: $ref: '#/components/schemas/Common.uuid' type: array securitySchemes: ApiKeyAuth: in: header name: X-Api-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.