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

# Start Agent Run (Stream)

`POST /agent/v1/agents/{agentId}/runs/stream`

## Request

- Base URL: `https://api.zoominfo.com/gtm`
- URL: `https://api.zoominfo.com/gtm/agent/v1/agents/{agentId}/runs/stream`
- 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 agent run and streams progress and output over Server Sent
Events (`text/event-stream`).

The first event includes the runId as `task.id`. Store this value so you can
retrieve the run later with
[Get Agent Run](ref:agentscontroller_getagentrun) or reconnect using
[Resume Agent Run Stream](ref:agentscontroller_resumeagentrunstream).

The stream includes status updates and artifact content as the agent runs.
The first artifact represents the primary response and may contain text and
structured data. A final status update indicates that the run has reached a
terminal state.

This endpoint is available only for agents that support `STREAMING` in
`capabilities.executionModes`. The request uses the same message format and
`inputSchema` validation as
[Start Agent Run](ref:agentscontroller_startagentrun).
Customer-defined Agent Teams on the platform do not currently support streaming.
Agents that do not support streaming return `400 STREAMING_NOT_SUPPORTED`.

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

The request has succeeded.

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