Tasks

A task fixes a stored prompt, a model, and what one call may send. See Use tasks.

Running a task needs Call models. Reading tasks needs View usage and limits. Creating, changing, and deleting them is for people with Developer access or more, from the console; API keys cannot.

Run a task

{
  "input": "My order is late.",
  "variables": { "customer": "Amina" },
  "history": [
    { "role": "user", "content": "Hello" },
    { "role": "assistant", "content": "Habari. How can I help?" }
  ]
}

inputstring

The text to send, up to the task’s input size. Required when the task takes input, and refused when it takes none.

variablesobject

A value for each variable the task leaves open, each up to its size. A variable the task fixes is refused.

historyarray

Earlier messages of a conversation, oldest first, up to the task’s number and size. Each is { "role": "user" or "assistant", "content": "…" }.

streamboolean

true sends the answer as it is written. See Streaming a run.

The body can be up to 256 KB. Any other field is refused with validation_failed.

{
  "data": {
    "task": "support-reply",
    "model": "openai/gpt-oss-120b",
    "text": "Pole sana, Amina. Your order leaves the warehouse today.",
    "stopReason": "end",
    "usage": { "inputTokens": 212, "outputTokens": 19, "units": 6 }
  }
}

taskstring

The task that ran.

modelstring

The model that answered.

textstring

The answer. A reasoning model’s reasoning is left out.

jsonany

Only for a task with JSON answers: the answer parsed as JSON, matching the task’s schema.

stopReasonstring

end when the model finished, max_tokens when it reached the task’s limit, or refused when it would not answer.

usageobject

inputTokens, outputTokens, and units: what the run used.

The answer has the headers X-Request-Id, and X-Ai-Processed-In naming the country it ran in.

Streaming a run

With "stream": true, the answer is server-sent events, each a JSON object with a type:

data: {"type":"text","text":"Pole sana, "}

data: {"type":"text","text":"Amina."}

data: {"type":"done","stopReason":"end","usage":{"inputTokens":212,"outputTokens":19,"units":6}}

• text holds the next piece of the answer.
• done comes last, with stopReason, usage, and json for a task with JSON answers.
• error holds an error problem document when the run fails after it started, and ends the stream. For a task with JSON answers, it comes in place of done when the answer is not JSON that matches the schema.

A stream that ends without done or error was cut off. Comments starting with : keep the connection open; skip them.

List tasks

The answer is a list of tasks, by name.

Read a task

{
  "name": "support-reply",
  "description": "Answers customers",
  "prompt": { "name": "support-agent", "version": 3, "latestVersion": 4 },
  "model": "openai/gpt-oss-120b",
  "maxTokens": 400,
  "temperature": null,
  "topP": null,
  "reasoningEffort": "low",
  "json": false,
  "schema": null,
  "input": { "maxBytes": 2000 },
  "variables": {
    "brand": { "value": "Duka" },
    "customer": { "maxBytes": 100 }
  },
  "history": { "messages": 10, "maxBytes": 8000 },
  "enabled": true,
  "worstCase": { "inputTokens": 12344, "outputTokens": 400, "units": 5623 },
  "createdBy": "01m3c081d2wj4g63qcr53pa1yh",
  "createdAt": "2026-09-29T08:00:00Z",
  "updatedBy": "01m3c081d2wj4g63qcr53pa1yh",
  "updatedAt": "2026-09-29T10:15:00Z"
}

prompt.latestVersioninteger

The prompt’s newest version, so you can see when the task is behind it.

worstCaseobject

The most one run can use, counting every byte a run may send as a token: inputTokens, outputTokens, and units. Real runs use far less input.

The other fields are as below.

Create a task

namestringRequired

1 to 63 lowercase letters, digits, and hyphens, starting with a letter or digit. It cannot change later.

descriptionstring

Up to 500 characters, for your team.

promptobjectRequired

{ "name", "version" }: the stored prompt and the version to use.

modelstringRequired

A model from the catalogue.

maxTokensintegerRequired

The most tokens an answer may have, from 1 to the model’s maximum.

temperaturenumber

0 to 2, or null for the model’s default.

topPnumber

0 to 1, or null for the model’s default.

reasoningEffortstring

low, medium, or high, for a model that reasons. Empty for the default.

jsonboolean

true asks for a JSON object.

schemaobject

A JSON schema for the answer, up to 16 KB. Needs json.

input.maxBytesintegerRequired

The most bytes of input a run may send, from 0 (none) to 32,768.

variablesobject

One entry for each of the prompt’s variables: { "value": "…" } to fix it, or { "maxBytes": n }, from 1 to 32,768, to let a run send it. The prompt’s variables and these must match.

history.messagesinteger

The most earlier messages a run may send, from 0 to 50. Needs input.

history.maxBytesinteger

The most bytes they may hold in all, up to 65,536. Needs history.messages.

enabledboolean

false refuses every run with task_disabled. true when left out.

The answer is 201 with the task. A name already in use is refused with task_exists, and a project holds up to 100 tasks.

Change a task

Send every field, as for creating one. The answer is the task. The next run uses the change.

Delete a task

The answer is 204, and runs of it are refused with task_not_found.