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

# Start Agent Run

`POST /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:execute`

Starts a new run for the specified agent.

By default, agent runs are asynchronous. The request returns the in-progress
run, including its run id in `data.id`, while execution continues in the
background. Use that run id with
[Get Agent Run](ref:agentscontroller_getagentrun) to retrieve the latest
status and final result.

To run the agent synchronously, set `returnImmediately: false` in
`data.attributes`. The connection remains open while the agent executes, up
to a maximum of 300 seconds. If the run does not complete within that
window, the response returns the in-progress run and execution continues in
the background. Use the returned run id from `data.id` with
[Get Agent Run](ref:agentscontroller_getagentrun) to retrieve the latest
status and final result.

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.

The request message is validated against the agent's `inputSchema`. Use
[Get Agent Details](ref:agentscontroller_getagent) before starting a run to
review the required input format.

## Path parameters

- `agentId` string, required

## Request body

- StartAgentRunRequestBody: Request body for starting an agent run: a JSON:API document, `{ "data": { "type": "StartAgentRunRequest", "attributes": { ... } } }`, per the ZI public-API standard for request bodies. The run input lives in `data.attributes`; the same body is used by Start Agent Run and Start Agent Run (Stream).
  - `data` StartAgentRunRequest, required: The run input as a JSON:API resource: `data.attributes` carries the message and optional contextId.
    - `type` string, required: The type of the resource
    - `attributes` StartAgentRunAttributes, required: Attributes for starting an agent run.
      - `message` 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: Conversation to continue this run within, as a UUID; omit to start fresh. Platform agents resume that conversation thread. Teams agents are single-shot: a supplied contextId is accepted and ignored (each Teams run gets a fresh server-minted context regardless). A malformed value returns `400` with a pointer to `/data/attributes/contextId`.
      - `returnImmediately` boolean: Whether the request returns immediately. Default `true` starts the run asynchronously and returns the in-progress run while execution continues in the background. Set `false` to keep the connection open while the agent executes, up to 300 seconds. If the run does not complete within that window, the response returns the in-progress run and execution continues in the background. Ignored by Start Agent Run (Stream), which always streams.
      - `taskId` string: OPTIONAL, and omitted for almost every call. Omit it to START a new run (the default, and the only mode implemented today). Set it to an existing run's id ONLY to CONTINUE that run when it is paused awaiting input (`TASK_STATE_INPUT_REQUIRED` / `TASK_STATE_AUTH_REQUIRED`): the message is delivered as the answer and the run resumes. This is A2A's `Message.taskId` (the run id is the taskId). Only agents whose `capabilities.interactive` is `true` accept a taskId; others return `400`. An unknown run returns `404`; a terminal or not-awaiting-input run returns `409`. No agent declares `interactive` yet, so continuation is not available in practice -- the field is specified for forward compatibility, not for use today.

## 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

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `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)