---
title: "Run an agent task"
method: POST
path: "/v1/tasks/{id}/run"
tags: ["Tasks"]
---

# Run an agent task

`POST /v1/tasks/{id}/run`

Execute an agent task by ID to generate AI output. Provide the necessary context items and configuration in the request body.

## Path parameters

- `id` string, required

## Request body

- TaskRunDto
  - `contextItems` union[], required — Array of context items - can include both predefined context items (with id and value) and custom context items (with name, question, and answer)
    - union
      - PredefinedContextItemDto
        - `id` string, required — Context item ID
        - `value` union, required — Context item value - format depends on the context item type: • INPUT, TEXTAREA, SELECT, IMAGE_ID, TOOL, CUSTOM: string • MULTISELECT, TAGS_INPUT: string[] (array of selected values) • KNOWLEDGE: KnowledgeItemDto[] (array of knowledge objects with knowledgeId and optional knowledgeExtractionPrompt) • CHECKBOX: string ("true" or "false")
          - string
          - string[]
          - object[]
            - `knowledgeId` string
            - `knowledgeExtractionPrompt` string
      - CustomContextItemDto
        - `name` string, required — The name/label of the custom context item
        - `question` string, required — The question/prompt for this context item (how it will be presented to the model)
        - `answer` string, required — The value/answer for this custom context item
        - `priority` number — The priority of this context item (higher priority = more important)
  - `version` number — Agent task version (optional, defaults to latest)
  - `toLanguage` string — Target output language for the completion (optional, defaults to EN-US)
  - `knowledgeIds` string[] — Array of knowledge IDs to use as context to power the agent
  - `attachmentIds` string[] — 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.
  - `toneId` string — Tone ID for the brand voice of the agent's output
  - `audienceId` string — The primary audience ID used to customize the agent's output for a target audience.
  - `additionalAudienceIds` string[] — Additional audience IDs to customize the agent's output for multiple target audiences in a single run, included alongside the primary `audienceId`.
  - `styleGuideId` string — Style Guide ID to apply writing rules to the agent's output
  - `tools` string[] — Array of tools to enable for agent task execution. Can include WEB_SEARCH and/or KNOWLEDGE_SEARCH

## Response `200`

Successfully executed agent task and generated output

- TaskRunResponseDto
  - `requestId` string
  - `resource` string
  - `data` TaskRunResult, required
    - `output` OutputItem[], required — Array of output items generated by the agent
      - `type` 'TEXT', required — The type of output item
      - `value` string, required — The output value content
    - `metadata` TaskRunResultMetadata
      - `credits` TaskRunCreditCost
        - `cost` number, required — Credits this run cost on your workspace plan.
      - `translation` TranslationRunMetadata
        - `tmsMatches` TmsSegmentMatchItem[] — Contextual translation-memory segment matches used to inform the translation. Present only for workspaces with a connected TMS integration.
          - `sourceSegment` string, required — The source segment that matched the translation memory
          - `matches` TmsMatch[], required — Approved translation-memory targets for this segment (highest score first)
            - `target` string, required — Approved translation-memory target text for the source segment.
            - `score` number, required — Match score between 0 and 1; higher is a closer match.

## Other responses

- `400` — Bad Request. The request body may be missing required fields or contain invalid data. Check the agent task input schema.
- `404` — Agent task not found. The specified app ID may not exist.
- `500` — Internal server error. Unable to run agent task.

---

[API](https://skmtc.net/jasper/apis/jasper-api.md) · [All operations](https://skmtc.net/jasper/apis/jasper-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/jasper/jasper-api/revisions/438914d9525e/schema)