---
title: "Get Agent Run"
method: GET
path: "/agent/v1/agents/{agentId}/runs/{runId}"
tags: ["Agents"]
---

# Get Agent Run

`GET /agent/v1/agents/{agentId}/runs/{runId}`

## Request

- Base URL: `https://api.zoominfo.com/gtm`
- URL: `https://api.zoominfo.com/gtm/agent/v1/agents/{agentId}/runs/{runId}`
- Auth: OAuth 2
  - Authorization code: `https://login.zoominfo.com`
  - Token URL: `https://okta-login.zoominfo.com/oauth2/default/v1/token` scopes: `api:agent:read`

Retrieves the current status and results of a specific agent run. Use the
run id returned in `data.id` by
[Start Agent Run](ref:agentscontroller_startagentrun) or the first event of
a streaming run by
[Start Agent Run (Stream)](ref:agentscontroller_streamagentrun).

By default, the endpoint returns the run's current state immediately. Set
`returnImmediately=false` to wait for the run to reach a terminal state.
Requests that remain open can wait for up to 300 seconds. If the request
times out before the run completes, the response returns the in-progress run
and execution continues in the background. Call this endpoint again with the
same run id to retrieve the latest status and results.

When the run completes, the first item in `artifacts` contains the primary
response and may include text and structured data. Additional artifacts,
when present, contain supplementary output.

For agents that support streaming, use
[Resume Agent Run Stream](ref:agentscontroller_resumeagentrunstream)
to follow the run in real time.

## Path parameters

- `agentId` string, required
- `runId` string, required

## Query parameters

- `returnImmediately` boolean

## Response `200`

Success

- AgentRunResponse: Response containing a single agent run.
  - `data` AgentRun, required: An agent run. The resource id is the runId, surfaced as taskId on every stream event.
    - `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.

## Other responses

- `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)