--- title: "List Agent Runs" method: GET path: "/agent/v1/agents/{agentId}/runs" tags: ["Agents"] --- # List Agent Runs `GET /agent/v1/agents/{agentId}/runs` ## Request - Base URL: `https://api.zoominfo.com/gtm` - URL: `https://api.zoominfo.com/gtm/agent/v1/agents/{agentId}/runs` - Auth: OAuth 2 - Authorization code: `https://login.zoominfo.com` - Token URL: `https://okta-login.zoominfo.com/oauth2/default/v1/token` scopes: `api:agent:read` Lists the run history for a specific agent, with the most recent runs returned first. Use this endpoint to review previous and active runs for the agent. To retrieve the current status and results of a specific run, use [Get Agent Run](ref:agentscontroller_getagentrun) instead. This endpoint does not start or modify a run. ## Path parameters - `agentId` string, required ## Query parameters - `filter[status]` AgentTaskState[] - `filter[createdAt]` string - `filter[initiatedBy]` string - `sort` string - `page[size]` integer - `page[after]` string ## Response `200` Success - AgentRunsListResponse: Response containing a page of agent runs. - `data` AgentRun[], required: The primary data of the document - `id` string, required: The unique identifier for the resource - `type` string, required: The type of the resource - `attributes` AgentRunAttributes, required: Attributes describing an agent run. - `agentId` string, required: The agent that was executed. - `status` AgentRunStatus, required: Current status of a run. - `state` 'TASK_STATE_UNSPECIFIED' | 'TASK_STATE_SUBMITTED' | 'TASK_STATE_WORKING' | 'TASK_STATE_INPUT_REQUIRED' | 'TASK_STATE_AUTH_REQUIRED' | 'TASK_STATE_COMPLETED' | 'TASK_STATE_FAILED' | 'TASK_STATE_CANCELED' | 'TASK_STATE_REJECTED', required: Task lifecycle states for a run. Terminal: COMPLETED, FAILED, CANCELED, REJECTED. Interrupted: INPUT_REQUIRED, AUTH_REQUIRED. Everything else is non-terminal. Consumers must tolerate unknown values, treating UNSPECIFIED as the fallback for states this version does not define. The service currently emits SUBMITTED, WORKING, COMPLETED, and FAILED (plus the UNSPECIFIED fallback). CANCELED and REJECTED are reserved for cancellation support; INPUT_REQUIRED and AUTH_REQUIRED are reserved for interactive runs. Consumers should handle all nine states. - `message` AgentMessage: A message: the shape carried by `status.message`, `history`, and the stream `message` frame (that frame is reserved for future use and not currently emitted). - `messageId` string, required: Unique message identifier. - `contextId` string: Conversation this message belongs to. - `taskId` string: Run this message belongs to (the runId). - `role` 'ROLE_UNSPECIFIED' | 'ROLE_USER' | 'ROLE_AGENT', required: Who a message is from. - `parts` AgentArtifactPart[], required: The message's content parts. - `text` string: Inline text content (text part). - `file` AgentFileContent: File content: exactly one of `uri` (a link, e.g. the platform's token-gated document route) or `bytes` (base64). `name` is always present on emitted files (the server falls back to the object type rather than emit a nameless file). - … - `data` unknown - `metadata` object: Producer-defined metadata for this part. - `metadata` object: Producer-defined metadata. - `timestamp` string, date-time: When this state was entered. - `executionMode` 'SYNC' | 'STREAMING' | 'ASYNC', required: Execution modes an agent supports. - `input` AgentRunMessage, required: The caller's message to the agent -- the run's entire input, as an ordered list of content parts (the same part shape artifacts use). There is no `role` (the sender is always the caller) and no message id (the run itself is the identity), so `parts` is the whole of it. Parts by kind: `text` parts carry prose and are joined into the agent's prompt; a `data` part carries the structured argument object the agent's `inputSchema` data entry types; `file` parts are declared in the shape but not yet accepted. AT MOST ONE `data` part may be present -- parts have no names and their order carries no meaning, so a second anonymous payload would be structure no schema can address; nest multiple structured payloads inside the one data object instead. - `parts` AgentArtifactPart[], required: The message's content parts. Each is exactly one of `text`, `file`, or `data`; at most one `data` part is allowed. - `text` string: Inline text content (text part). - `file` AgentFileContent: File content: exactly one of `uri` (a link, e.g. the platform's token-gated document route) or `bytes` (base64). `name` is always present on emitted files (the server falls back to the object type rather than emit a nameless file). - `uri` string, uri: Link to downloadable content (e.g. a generated document). - `bytes` string: Base64-encoded binary content. - `name` string: Display filename. - `mimeType` string: MIME type of the file content. - `data` unknown - `metadata` object: Producer-defined metadata for this part. - `contextId` string: The conversation this run belongs to, as a UUID, identical across the run's POST response, Get Agent Run, stream, and resume. For platform agents it is the conversation thread and can be passed back on a later run to continue it. For Teams agents it is always present -- a fresh server-minted per-run UUID -- but is an identity handle only: passing it back resumes nothing (Teams runs are single-shot). - `artifacts` AgentRunArtifact[]: The run's artifacts; present when the terminal state is COMPLETED, and at least one is always present then. The FIRST artifact is the run's response: its text part is the reply prose, and a data part beside it carries the structured result when the agent produced one. Further artifacts are supporting deliverables, e.g. generated documents (file parts) or referenced objects. - `artifactId` string, required: Unique identifier of the artifact within the run. - `name` string: Display name of the artifact. - `description` string: What the artifact contains. - `parts` AgentArtifactPart[], required: The artifact's content parts. May carry more than one part, e.g. a text rendition and a structured `data` part. - `text` string: Inline text content (text part). - `file` AgentFileContent: File content: exactly one of `uri` (a link, e.g. the platform's token-gated document route) or `bytes` (base64). `name` is always present on emitted files (the server falls back to the object type rather than emit a nameless file). - `uri` string, uri: Link to downloadable content (e.g. a generated document). - `bytes` string: Base64-encoded binary content. - `name` string: Display filename. - `mimeType` string: MIME type of the file content. - `data` unknown - `metadata` object: Producer-defined metadata for this part. - `metadata` object: Producer-defined metadata, e.g. the tool that created the artifact. - `error` AgentRunError: Machine-readable failure details. Present when the run FAILED; may be present for CANCELED when a safe cancellation reason exists. - `code` string, required: Stable machine-readable error code, e.g. `AGENT_EXECUTION_FAILED`. - `message` string, required: Human-readable, sanitized explanation. Never carries internal system detail. - `retryable` boolean: Whether retrying the identical request may succeed. Defaults to false. - `durationMs` integer: Total execution duration in milliseconds. Present once the run reaches a terminal state. - `initiatedBy` RunInitiator, required: The identity that initiated the run. - `type` 'USER' | 'WORKFLOW' | 'API', required: The kind of identity that initiated a run. - `id` string, required: Identifier of the initiator (user id, workflow id, or API client id). - `history` AgentMessage[]: Task history: prior messages exchanged within the run's context. - `messageId` string, required: Unique message identifier. - `contextId` string: Conversation this message belongs to. - `taskId` string: Run this message belongs to (the runId). - `role` 'ROLE_UNSPECIFIED' | 'ROLE_USER' | 'ROLE_AGENT', required: Who a message is from. - `parts` AgentArtifactPart[], required: The message's content parts. - `text` string: Inline text content (text part). - `file` AgentFileContent: File content: exactly one of `uri` (a link, e.g. the platform's token-gated document route) or `bytes` (base64). `name` is always present on emitted files (the server falls back to the object type rather than emit a nameless file). - `uri` string, uri: Link to downloadable content (e.g. a generated document). - `bytes` string: Base64-encoded binary content. - `name` string: Display filename. - `mimeType` string: MIME type of the file content. - `data` unknown - `metadata` object: Producer-defined metadata for this part. - `metadata` object: Producer-defined metadata. - `extensions` object: Extension data contributed to the run. - `meta` AgentRunMeta: Timestamps and metering for an agent run. - `createdAt` string, date-time, required: When the run was created. - `startedAt` string, date-time: When execution actually began. - `completedAt` string, date-time: When the run reached a terminal state. - `updatedAt` string, date-time, required: When the run last changed. - `totalCredits` integer: Total AI credits consumed. Present once the run reaches a terminal state. - `meta` CursorPagingMeta: Metadata for a cursor-paged collection. - `page` CursorPageInfo, required: Page details for a cursor-paged collection. - `pageSize` integer, required: The page size as specified by the request. - `totalCount` integer, required: The total count of results matching the current filters. - `links` CursorPagingLinks: Links for a cursor-paged collection. `next` is omitted on the last page and `prev` on the first. - `self` string, uri: The link that generated the current response document - `prev` string, uri: A link to the previous page of data - `next` string, uri: A link to the next page of data ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `429`: Too Many Requests --- [API](https://skmtc.dev/zoominfo/apis/agent-api-v1.md) - [All operations](https://skmtc.dev/zoominfo/apis/agent-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/zoominfo/apis/agent-api-v1/revisions/01784a5ae274?raw)