Tasks

Run an agent task

Changed on Nov 3, 2026

Execute an agent task by ID to generate AI output. The selected task version supplies its saved agent defaults for omitted IQ fields; valid request IQ fields take precedence. Provide the necessary context items and configuration in the request body.

post/v1/tasks/{id}/run

Request

Base URL
https://api.jasper.ai
URL
https://api.jasper.ai/v1/tasks/{id}/run
Auth
- API key in header X-API-Key
- or OAuth 2
  Authorization code: https://api.jasper.ai/oauth2/authorize
  Token URL: https://api.jasper.ai/oauth2/token scopes: user

Path parameters

idstring required

Example:agt_0190f3a1b2c34d5e6f7a8b9c0d1e2f3a

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

Request body

versionnumber

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

toLanguagestring

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

knowledgeIdsstring[]

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

attachmentIdsstring[]

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.

toneIdstring

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

audienceIdstring

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

styleGuideIdstring

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

visualGuidelineIdstring

Visual Guidelines V2 item ID (iqi_…) to use as visual context for this run. The guideline must be active, ready, and accessible in the request workspace. Omitting this field preserves the agent’s saved visual context.

toolsstring[]

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

fallbackToWorkspaceDefaultIqboolean

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.

Example request

{
  "contextItems": [
    {
      "id": "70346737-878b-4329-a4d6-9a054efef508",
      "value": [
        "Registration reminder email",
        "Confirmation email"
      ]
    },
    {
      "name": "Greeting",
      "question": "Who is the person that you want me to greet in the registration reminder email?",
      "answer": "John Doe"
    }
  ],
  "version": 1,
  "toLanguage": "EN-US",
  "knowledgeIds": [
    "kno_123",
    "kno_456"
  ],
  "products": [
    {
      "productId": "prd_073D2D49094A4AED991A47B614522579",
      "attributeIds": [
        "atr_535B1EC15F5F41EAB1B400E9ED4077B6"
      ]
    }
  ],
  "attachmentIds": [
    "tmp_2ee766eaa4ef48e59da1d9602bfecf2d"
  ],
  "toneId": "ton_2ee766eaa4ef48e59da1d9602bfecf2d",
  "audienceId": "aud_123",
  "audienceIds": {
    "primary": "aud_2ee766eaa4ef48e59da1d9602bfecf2d",
    "secondary": [
      "aud_7c1f0b9d2e4a4f6b8d3c5a1e9f0b2c4d"
    ]
  },
  "styleGuideId": "sty_123",
  "visualGuidelineId": "iqi_01a18cbff6317442800af05496eec95b",
  "tools": [
    "WEB_SEARCH",
    "KNOWLEDGE_SEARCH"
  ]
}

Response

Successfully executed agent task and generated output

requestIdstring

resourcestring

Example response

{
  "requestId": "bce766ea-a4ef-48e5-9da1-d9602bfecf2d",
  "resource": "tasks",
  "data": {
    "output": [
      {
        "type": "TEXT",
        "value": "This is the generated content from the agent..."
      }
    ],
    "metadata": {
      "credits": {
        "cost": 40
      },
      "translation": {
        "tmsMatches": [
          {
            "sourceSegment": "Click Save to continue.",
            "matches": [
              {
                "target": "Klicken Sie auf Speichern, um fortzufahren.",
                "score": 1
              }
            ]
          }
        ]
      }
    }
  }
}

Changes

Nov 3, 20263d5be7408661 Revision changes
- breaking
  added to the // response property oneOf list for the response status
- breaking
  the // response's property type changed from object to no type for status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- warning
  removed the request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  the request property default value was removed

Operation history