Skip to main content
POST
List Executions
Use this API to fetch a paginated page of execution documents for the workspace, always ordered by startedAt descending (newest first). Designed for Console / Portal listing pages. Get Execution remains the only way to fetch a single execution’s per-URL results subcollection; list never includes results. Each row is identical to the execution object from Get Execution (without includeResults), including the metadata: { documentId, organizationId } block carrying the IDs you passed on Run Execution.

Endpoint

POST https://api.velt.dev/v2/agents/execution/list

Headers

x-velt-api-key
string
required
Your API key.
x-velt-auth-token
string
required

Body

Filter combinations (whitelist). Exactly one of these three shapes is accepted. Every other combination, including {}, { organizationId } alone, { documentId } alone, { agentId, organizationId } (no docId), and { agentId, documentId } (no orgId), is rejected with INVALID_ARGUMENT.
  1. { agentId }: all executions of a single agent across the workspace.
  2. { organizationId, documentId }: all executions on a single document (any agent).
  3. { agentId, organizationId, documentId }: executions of a single agent on a single document.

Params

data
object
required

Example Requests

1. Org + doc, first page (combo #2)

2. Next page via cursor

3. Agent only (combo #1)

4. All three (combo #3)

Response

Success Response

Failure Response

Errors:
  • INVALID_ARGUMENT: filter combo violates the 3-shape whitelist; pageSize out of range; pageToken empty/malformed/undecryptable; or pageToken references a now-deleted execution.
  • NOT_FOUND: workspace store database could not be resolved.