Run an agent task with streaming response

post

https://api.jasper.ai/v1/tasks/{id}/run/stream

Execute an agent task by ID to generate AI output with Server-Sent Events (SSE) streaming. The selected task version supplies its saved agent defaults for omitted IQ fields; valid request IQ fields take precedence. Provides real-time content as it is generated.

Path Params

string

required

The external ID (agt_…) or internal UUID of the agent task to run

Body Params

contextItems

array

required

Array of context items - can include both predefined context items (with id and value) and custom context items (with name, question, and answer)

contextItems*

version

number

Agent task version (optional, defaults to latest). A pinned version uses that version's saved agent defaults for omitted IQ fields.

toLanguage

string

Target output language for the completion. Blank values are treated as omitted, allowing the selected task version to apply its saved language.

knowledgeIds

array of strings

Array of knowledge IDs to use as context to power the agent

knowledgeIds

products

array of objects

A list of Products to use as context to power the agent. Reference each Product by ID, optionally narrowing which of its attributes are included. Discover Products with GET /v1/products.

products

attachmentIds

array of strings

Array of temporary attachment IDs (prefixed tmp_) to use as ad-hoc context for this run. Create attachments up front via POST /v1/attachments and pass the returned IDs here. Temporary attachments are intended for short-lived context (the same attachment can be referenced across retries of the same run) and are not durable — use knowledgeIds for content that should persist in your workspace.

attachmentIds

toneId

string

Tone ID for the brand voice of the agent's output

audienceId

string

The audience ID used to customize the agent's output for a target audience.

audienceIds

object

Structured audience selection with a primary audience and optional secondary audiences. When both audienceId and audienceIds are sent, audienceIds wins.

styleGuideId

string

Style Guide ID to apply writing rules to the agent's output

tools

array of strings

Array of tools to enable for agent task execution. Can include WEB_SEARCH and/or KNOWLEDGE_SEARCH

tools

Allowed:

fallbackToWorkspaceDefaultIq

boolean

Defaults to false

When true, any Jasper IQ your request leaves unspecified falls back to your workspace default for that type (style guide, brand voice, and audience). IQ you pass explicitly always wins, and a type with no workspace default stays unset. Defaults to false, so requests that omit this option behave exactly as before.

Response

200Stream of step updates and text chunks. The terminal event includes outputs; IMAGE outputs carry assetId, name, and a temporary signed download URL in url.