space.ai.run()

Run a task with your input, and get its answer whole or as it is written.

Runs a task: a prompt, a model, and limits set in the console. You send only the input. With stream: true, it returns the answer as the model writes it.

function run(
  task: string,
  options: TaskOptions & { stream: true }
): Promise<TaskStream>

function run(
  task: string,
  options?: TaskOptions & { stream?: false }
): Promise<TaskReply>

Parameters

taskstringRequired: The task’s name, such as summarise-note: 1 to 63 lowercase letters, digits, and hyphens.
options.inputstring: The text to send. Required when the task takes input, and refused when it takes none. It can’t be blank, and the service checks it against the task’s size.
options.variablesRecord<string, string>: A value for each variable the task leaves open. A variable the task fixes is refused.
options.historyTurn[]: Earlier messages of a conversation, oldest first, up to 50, and up to the task’s own number and size. Each is { role: "user" | "assistant", content }.
options.streamboolean: true returns a task stream instead of a task reply. false by default.
options.signalAbortSignal: Cancels the call, including a stream that is still being read.
options.timeoutMsnumber: How long the call may take, in milliseconds, including reading a stream. 600,000 (10 minutes) when you leave it out.

The model, the prompt, and every setting come from the task, so run() takes none of them. An option this page does not list fails with validation_failed, before anything is sent.

Returns

A promise of a task reply, which settles when the whole answer has arrived. With stream: true, a promise of a task stream, which settles as soon as the answer starts to arrive.

A run is not sent again after a network failure or a timeout, because the model may already have started. It is sent again, up to retries times, only when it was refused with 429 or 503 before any work began.

Errors

Code	When
`validation_failed`	The name, the input, a variable, or an earlier message breaks a rule above or the task’s own. `issues` names each field
`task_not_found`	The project has no task with that name
`task_disabled`	The task is turned off
`unit_limit_reached`	The run could go over the AI units the project may use this month
`rate_limited`	The project sent more requests or tokens this minute than its plan allows
`model_unavailable`	The model cannot answer right now, or stopped partway through a stream
`answer_invalid`	For a task with JSON answers, the model did not answer with JSON that matches the schema
`answer_cut_off`	For a task with JSON answers, the answer reached the task’s token limit before its JSON finished
`stream_interrupted`	A stream ended before the answer finished
`timeout`	The call took longer than `timeoutMs`

Every call can also fail with the codes shared by all of space. See SpaceError, and for every AI code, AI errors.

Example

summarise.ts

import { space } from "digitospace"

const reply = await space.ai.run("summarise-note", {
  input: "The ferry to Zanzibar leaves Dar es Salaam at 7:00 and takes 2 hours.",
})

console.log(reply.text)
console.log(`${reply.usage.units} AI units`)

Stream a conversation

support.ts

import { space, type Turn } from "digitospace"

const history: Turn[] = [
  { role: "user", content: "Habari" },
  { role: "assistant", content: "Nzuri. How can I help?" },
]

const stream = await space.ai.run("support-reply", {
  input: "My order is late.",
  variables: { customer: "Amina" },
  history,
  stream: true,
})

for await (const chunk of stream) {
  process.stdout.write(chunk.text)
}

const { stopReason, usage } = await stream.done()
console.log(`\n${stopReason}, ${usage.units} AI units`)

Last updated 30 September 2026