---
updatedAt: 2026-04-21T01:30:12.000Z
agentTools:
  projectIndex: https://developers.jasper.ai/llms.txt
---

# Run an agent task

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.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "paths": {
    "/v1/tasks/{id}/run": {
      "post": {
        "description": "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.",
        "operationId": "runTask",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The external ID (agt_…) or internal UUID of the agent task to run",
            "schema": {
              "example": "agt_0190f3a1b2c34d5e6f7a8b9c0d1e2f3a",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskRunDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully executed agent task and generated output",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskRunResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request. The request body may be missing required fields or contain invalid data. Check the agent task input schema."
          },
          "404": {
            "description": "Agent task not found. The specified app ID may not exist."
          },
          "500": {
            "description": "Internal server error. Unable to run agent task."
          }
        },
        "security": [
          {
            "X-API-Key": []
          },
          {
            "oauth2": [
              "user"
            ]
          }
        ],
        "summary": "Run an agent task",
        "tags": [
          "Tasks"
        ]
      }
    }
  },
  "info": {
    "title": "Jasper API",
    "description": "Jasper API",
    "version": "1.0",
    "contact": {}
  },
  "tags": [
    {
      "name": "Tasks",
      "description": ""
    }
  ],
  "servers": [
    {
      "url": "https://api.jasper.ai"
    }
  ],
  "components": {
    "securitySchemes": {
      "X-API-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Workspace authentication using API key tokens in the X-API-Key header."
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.jasper.ai/oauth2/authorize",
            "tokenUrl": "https://api.jasper.ai/oauth2/token",
            "refreshUrl": "https://api.jasper.ai/oauth2/token",
            "scopes": {
              "user:read": "Read user information",
              "user": "Read and write user information"
            }
          }
        },
        "description": "User-level authentication using OAuth bearer tokens in the Authorization header."
      }
    },
    "schemas": {
      "PredefinedContextItemDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Context item ID",
            "example": "729d2dd3-9ec6-4930-b216-48b8923671ca"
          },
          "value": {
            "description": "Context item value - format depends on the context item type:\n• INPUT, TEXTAREA, SELECT, IMAGE_ID, TOOL, CUSTOM: string\n• MULTISELECT, TAGS_INPUT: string[] (array of selected values)\n• KNOWLEDGE: KnowledgeItemDto[] (array of knowledge objects with knowledgeId and optional knowledgeExtractionPrompt)\n• CHECKBOX: string (\"true\" or \"false\")",
            "examples": {
              "stringValue": {
                "summary": "Text input (INPUT/TEXTAREA/SELECT/IMAGE_ID/TOOL/CUSTOM)",
                "value": "Sample text content"
              },
              "arrayValue": {
                "summary": "Multi-select or tags (MULTISELECT/TAGS_INPUT)",
                "value": [
                  "option1",
                  "option2",
                  "option3"
                ]
              },
              "knowledgeValue": {
                "summary": "Knowledge items (KNOWLEDGE type)",
                "value": [
                  {
                    "knowledgeId": "kno_123",
                    "knowledgeExtractionPrompt": "Extract statistics, facts, and important timeline information"
                  }
                ]
              },
              "checkboxValue": {
                "summary": "Checkbox (CHECKBOX type)",
                "value": "true"
              }
            },
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "knowledgeId": {
                      "type": "string"
                    },
                    "knowledgeExtractionPrompt": {
                      "type": "string"
                    }
                  }
                }
              }
            ]
          }
        },
        "required": [
          "id",
          "value"
        ]
      },
      "CustomContextItemDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name/label of the custom context item",
            "example": "Greeting"
          },
          "question": {
            "type": "string",
            "description": "The question/prompt for this context item (how it will be presented to the model)",
            "example": "Who is the person that you want me to greet in the registration reminder email?"
          },
          "answer": {
            "type": "string",
            "description": "The value/answer for this custom context item",
            "example": "Tim Everett"
          },
          "priority": {
            "type": "number",
            "description": "The priority of this context item (higher priority = more important)",
            "example": 1,
            "default": 0
          }
        },
        "required": [
          "name",
          "question",
          "answer"
        ]
      },
      "ProductInputDto": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string",
            "description": "The ID of the Product IQ product to attach as context (`prd_`, or legacy `itm_`).",
            "example": "prd_073D2D49094A4AED991A47B614522579"
          },
          "attributeIds": {
            "description": "Optional attribute IDs to limit which of the product's attributes are included. Omit to include all attributes. The product name is always included. Discover attribute IDs via `GET /v1/products/attributes`.",
            "example": [
              "atr_535B1EC15F5F41EAB1B400E9ED4077B6"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "productId"
        ]
      },
      "AudienceIdsDto": {
        "type": "object",
        "properties": {
          "primary": {
            "type": "string",
            "description": "Primary audience ID.",
            "example": "aud_2ee766eaa4ef48e59da1d9602bfecf2d"
          },
          "secondary": {
            "description": "Secondary audience IDs included alongside the primary audience. At most 24.",
            "example": [
              "aud_7c1f0b9d2e4a4f6b8d3c5a1e9f0b2c4d"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "primary",
          "secondary"
        ]
      },
      "TaskRunDto": {
        "type": "object",
        "properties": {
          "contextItems": {
            "type": "array",
            "description": "Array of context items - can include both predefined context items (with id and value) and custom context items (with name, question, and answer)",
            "example": [
              {
                "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"
              }
            ],
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/PredefinedContextItemDto"
                },
                {
                  "$ref": "#/components/schemas/CustomContextItemDto"
                }
              ]
            }
          },
          "version": {
            "type": "number",
            "description": "Agent task version (optional, defaults to latest). A pinned version uses that version's saved agent defaults for omitted IQ fields.",
            "example": 1
          },
          "toLanguage": {
            "type": "string",
            "description": "Target output language for the completion. Blank values are treated as omitted, allowing the selected task version to apply its saved language.",
            "example": "EN-US"
          },
          "knowledgeIds": {
            "description": "Array of knowledge IDs to use as context to power the agent",
            "example": [
              "kno_123",
              "kno_456"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "products": {
            "description": "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`.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductInputDto"
            }
          },
          "attachmentIds": {
            "description": "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.",
            "example": [
              "tmp_2ee766eaa4ef48e59da1d9602bfecf2d"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "toneId": {
            "type": "string",
            "description": "Tone ID for the brand voice of the agent's output",
            "example": "ton_2ee766eaa4ef48e59da1d9602bfecf2d"
          },
          "audienceId": {
            "type": "string",
            "description": "The audience ID used to customize the agent's output for a target audience.",
            "example": "aud_123"
          },
          "audienceIds": {
            "description": "Structured audience selection with a primary audience and optional secondary audiences. When both `audienceId` and `audienceIds` are sent, `audienceIds` wins.",
            "allOf": [
              {
                "$ref": "#/components/schemas/AudienceIdsDto"
              }
            ]
          },
          "styleGuideId": {
            "type": "string",
            "description": "Style Guide ID to apply writing rules to the agent's output",
            "example": "sty_123"
          },
          "tools": {
            "type": "array",
            "description": "Array of tools to enable for agent task execution. Can include WEB_SEARCH and/or KNOWLEDGE_SEARCH",
            "example": [
              "WEB_SEARCH",
              "KNOWLEDGE_SEARCH"
            ],
            "items": {
              "type": "string",
              "enum": [
                "WEB_SEARCH",
                "KNOWLEDGE_SEARCH"
              ]
            }
          },
          "fallbackToWorkspaceDefaultIq": {
            "type": "boolean",
            "description": "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.",
            "default": false
          }
        },
        "required": [
          "contextItems"
        ]
      },
      "OutputItem": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "TEXT",
              "IMAGE"
            ],
            "example": "TEXT",
            "description": "The type of output item"
          },
          "id": {
            "type": "string",
            "description": "Persisted workspace image ID for IMAGE outputs."
          },
          "name": {
            "type": "string",
            "description": "Display name of the generated image."
          },
          "value": {
            "type": "string",
            "example": "This is the generated content from the agent...",
            "description": "Generated text for TEXT outputs; a temporary signed download URL for IMAGE outputs."
          }
        },
        "required": [
          "type",
          "value"
        ]
      },
      "TaskRunCreditCost": {
        "type": "object",
        "properties": {
          "cost": {
            "type": "number",
            "example": 40,
            "description": "Credits this run cost on your workspace plan."
          }
        },
        "required": [
          "cost"
        ]
      },
      "TmsMatch": {
        "type": "object",
        "properties": {
          "target": {
            "type": "string",
            "example": "Klicken Sie auf Speichern, um fortzufahren.",
            "description": "Approved translation-memory target text for the source segment."
          },
          "score": {
            "type": "number",
            "example": 1,
            "description": "Match score between 0 and 1; higher is a closer match."
          }
        },
        "required": [
          "target",
          "score"
        ]
      },
      "TmsSegmentMatchItem": {
        "type": "object",
        "properties": {
          "sourceSegment": {
            "type": "string",
            "example": "Click Save to continue.",
            "description": "The source segment that matched the translation memory"
          },
          "matches": {
            "description": "Approved translation-memory targets for this segment (highest score first)",
            "example": [
              {
                "target": "Klicken Sie auf Speichern, um fortzufahren.",
                "score": 1
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TmsMatch"
            }
          }
        },
        "required": [
          "sourceSegment",
          "matches"
        ]
      },
      "TranslationRunMetadata": {
        "type": "object",
        "properties": {
          "tmsMatches": {
            "description": "Contextual translation-memory segment matches used to inform the translation. Present only for workspaces with a connected TMS integration.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TmsSegmentMatchItem"
            }
          }
        }
      },
      "TaskRunResultMetadata": {
        "type": "object",
        "properties": {
          "credits": {
            "description": "Credit cost of this run. Present only when the workspace meters this operation; reflects what was billed.",
            "allOf": [
              {
                "$ref": "#/components/schemas/TaskRunCreditCost"
              }
            ]
          },
          "translation": {
            "description": "Translation-specific run metadata. Present only for translation tasks that emit it.",
            "allOf": [
              {
                "$ref": "#/components/schemas/TranslationRunMetadata"
              }
            ]
          }
        }
      },
      "TaskRunResult": {
        "type": "object",
        "properties": {
          "output": {
            "description": "Array of output items generated by the agent",
            "example": [
              {
                "type": "TEXT",
                "value": "This is the generated content from the agent..."
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OutputItem"
            }
          },
          "metadata": {
            "description": "Optional run metadata. Present only for features that emit it (e.g. TMS segment matches).",
            "allOf": [
              {
                "$ref": "#/components/schemas/TaskRunResultMetadata"
              }
            ]
          }
        },
        "required": [
          "output"
        ]
      },
      "TaskRunResponseDto": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "example": "bce766ea-a4ef-48e5-9da1-d9602bfecf2d"
          },
          "resource": {
            "type": "string",
            "example": "tasks"
          },
          "data": {
            "$ref": "#/components/schemas/TaskRunResult"
          }
        },
        "required": [
          "data"
        ]
      }
    }
  },
  "x-readme": {
    "metrics-enabled": false
  }
}
```