Deployments.ai Docs
Platform

Threads and runs

Conversations as threads, executions as runs, and how to submit, inspect, cancel, retry, and replay them.

A thread is one conversation with an agent deployment. A run is one execution of the agent on a thread. You submit a user message, the platform queues a run, and the run produces the assistant's reply. Use threads and runs whenever your application talks to a deployed agent, and use the run routes to follow progress and recover from failures.

Threads hold the conversation

A thread belongs to one agent deployment, or to the execution binding of a preview or evaluation. It stores the messages of the conversation in order.

Thread fieldMeaning
agentDeploymentId or executionBindingIdWhat the thread runs on.
executionPurposecustomer for a deployment, preview or evaluation for an execution binding.
titleAt most 120 characters.
workspaceIdThe workspace the thread is scoped to, when it has one.
pinnedAgentReleaseIdThe release this thread's runs stay on. See canary releases.
continuedFromThreadIdThe predecessor thread, for a continued thread.
archivedWhether the thread accepts new runs.

Each message has a role (user, assistant, system, or tool), a sequence number, and its content. Large message bodies come back as a short-lived bodyAccess download instead of an inline body.

You get a thread in one of two ways:

  • Create it with POST /v1/threads. The deployment must be ready and running, or the request fails with deployment_unavailable.
  • Submit a run without threadId. The platform creates the thread and titles it with your title or the first line of the message.

Archive a thread to close it. Archiving fails with 409 thread_active while any of its runs is not terminal, and archiving an archived thread returns it unchanged. An archived thread rejects new runs and replays with 409 thread_archived.

To tie a thread to one of your end users, send your own ID for that user as endUserId when you create the thread, either on POST /v1/threads or on the run submission that creates it. The platform keeps only a keyed pseudonym of the ID and never returns it. The end user is set once: a continued thread inherits it, and naming a different end user fails with 409 end_user_mismatch. IDs may not start with channel:, which the platform reserves for channel users. Naming the end user lets you erase every thread of that end user later.

GET /v1/threads lists customer threads. Preview and evaluation threads appear only when you filter by executionBindingId.

Submit a run

POST /v1/agent-deployments/{agentDeploymentId}/runs adds a user message to a thread and queues a run. The request needs an Idempotency-Key header.

Body fieldRules
contentRequired. The user message, at most 256 KiB of UTF-8.
threadIdContinue an existing thread. Omit it to start a new one.
titleTitle for a new thread, at most 120 characters.
workspaceIdWorkspace scope for a new thread.
endUserIdYour ID for the end user a new thread belongs to, 1 to 256 characters. Refused for an existing thread of another end user.
runContextPer-run data for the model, at most 256 KiB. See Context management.
inputArtifactsOne to eight type: "input" artifact IDs: images, audio, or documents. See Context management.
responseFormatA JSON schema contract for the final answer. See Structured output.
responsePublicationexternal keeps the answer out of visible history until you publish it. See Publish automation output.
rebaseReleasetrue drops the thread's pinned release and selects again.

The response is 202 with created, message, run, and thread. If you repeat a request with the same idempotency key, you get the original submission back with created: false.

Before it queues the run, the platform checks the deployment, the release, and the request:

ErrorStatusCause
deployment_unavailable409The deployment is not ready and running.
release_unavailable409The selected release is not active or not selectable on the deployment.
trigger_not_allowed409The release declares spec.triggers without api.
thread_archived409The thread is archived.
workspace_unavailable409The workspace is not active.
invalid_request400The body fails validation, for example content over 256 KiB.
response_format_conflict422The request's responseFormat differs from the one the release pins.
budget_exhausted429A budget has no capacity left.
input_artifact_unavailable404An input artifact is missing or outside the caller's private scope.
input_file_<reason>422An input artifact resolved to unusable, such as input_file_no_text for a PDF with no readable text. The message names the file. See Artifacts.
model_image_input_unsupported422An input artifact is an image and the release's primary model cannot read images. See Models.
model_image_input_unknown422An input artifact is an image and the platform does not know whether the release's primary model reads images.
end_user_mismatch409endUserId differs from the end user of the thread or its predecessor.
end_user_erasure_in_progress409An erasure of the new thread's end user is still running.

Run lifecycle

A run moves through these statuses:

StatusMeaning
queuedWaiting for a worker, or for a free slot under the organization's concurrent run limit. A run also returns here after an approval, a tool result, or an execution checkpoint.
runningA worker is executing the agent.
waiting-for-approvalA tool call needs a human decision. See Approvals and client tools.
waiting-for-toolA tool call is running outside the worker, such as a client tool or an awaited sub-agent.
completedThe run finished and its answer is final.
failedThe run stopped with an error.
canceledSomeone canceled the run.

completed, failed, and canceled are terminal. An approval decision moves a waiting run back to queued, or to failed when the approval is rejected or expired. A completed tool result moves a waiting-for-tool run back to queued. A failed client tool or an expired one also resumes the run, and so does a failed awaited sub-agent, so the model can recover. You can cancel a run in any status that is not terminal.

Every run records the release it runs in agentReleaseId and why in releaseSelection. It also carries trigger, executionPurpose, a traceId for observability, and replayedFromRunId when it is a replay. A run that a schedule or heartbeat fire started carries automation, which names the automation and the fire. See Schedules and heartbeats.

The worker increments attempt each time it claims the run. After 30 claims that were not execution checkpoints, the run fails with run_retry_limit_exhausted. checkpointCount counts the run's execution checkpoints so far, and starts at 0. Context management explains execution checkpoints.

Concurrent run limit

Each organization can execute a limited number of runs at once, set by its concurrentRuns limit. Only a run in running holds one of these slots. A run that waits for an approval, a client tool, or an awaited sub-agent holds none, so paused runs never block other work. When the paused run returns to queued, it needs a free slot again.

When every slot is in use, new runs stay queued. The worker checks again every 30 to 60 seconds and starts the run once a slot is free. A check that finds no free slot does not change the run, so waiting does not use up attempt. Runs on the same thread start in the order you submitted them. Runs on different threads have no fixed order, so a run submitted later on another thread can start first.

A run fails with organization_concurrency_wait_expired when it has waited more than 6 hours since it last entered queued and the organization is still at its limit. Retry it with POST /v1/runs/{runId}/retry once the organization has capacity.

To see your organization's limit, run deployments org limits $ORGANIZATION_ID. Versioning and limits lists every organization limit.

Cancel, retry, and replay

ActionRouteApplies toResult
CancelPOST /v1/runs/{runId}/cancelRuns that are not terminalThe run becomes canceled. A pending approval becomes rejected and its tool call fails.
RetryPOST /v1/runs/{runId}/retryfailed runsThe same run returns to queued with attempt reset to 0.
ReplayPOST /v1/runs/{runId}/replaycompleted, failed, or canceled runsA new run on the same thread with a copy of the user message, release, runContext, inputArtifacts, and responseFormat.
  • Canceling a canceled run returns it again. Canceling a completed or failed run fails with 409 run_terminal.
  • Retrying a run in any other status fails with 409 run_not_retryable.
  • Replay needs an Idempotency-Key header, and the CLI generates one. Replaying a run that is not terminal fails with 409 run_not_replayable. Runs whose prompt body is stored outside the message cannot be replayed.
  • Retry and replay need the run's deployment to still be ready and its release to still be active, or they fail with 409 run_not_executable. For preview runs, the preview must not have expired (execution_binding_expired).
  • Retry and replay check budgets, so both can fail with 429 budget_exhausted.
  • Retry and replay check the organization's standing, so both fail with 403 organization_suspended while the organization is suspended.

Read results

  • GET /v1/threads/{threadId}/runs/{runId} and GET /v1/runs/{runId} return a run.
  • GET /v1/threads/{threadId}/runs/{runId}/message returns the run's finalized assistant message.
  • GET /v1/threads/{threadId}/messages pages through the thread's messages.
  • GET /v1/runs lists runs, and POST /v1/runs/search takes the same filters in the body. Filter by status, threadId, agentReleaseId, executionPurpose, and a creation time range. Set at most one of agentDeploymentId and executionBindingId. With neither, you get every run in the environment, newest first.
  • GET /v1/runs/{runId}/tool-calls lists the run's tool calls. A tool call that a model generation requested has modelCallIndex, the run's index of that generation, and modelAttemptId, the model attempt whose result requested it. The two fields appear together and never on tool-plan calls. The generation that read the tool's result has index modelCallIndex + 1. Both stay the same after the run resumes from a checkpoint, so use them rather than timestamps to group calls by generation.

To watch a run as it happens, read the thread stream. See Streaming.

Runtime logs

GET /v1/runs/{runId}/logs returns what the runtime logged while it executed a run, oldest first. Each line has a time, a level (debug, info, warn, or error), a source, a message, and the run's threadId and traceId. A line can also carry a spanId, a toolCallId, and up to 16 scalar attributes.

SourceWhat writes it
runtimeThe run lifecycle, memory recall, and brain retrieval.
modelModel generations starting, finishing, and failing.
toolTool calls starting, finishing, and failing, with the tool call's span.
sandboxSandboxes starting, running commands, and stopping.
hosted-codeWhat a hosted code tool printed, one line per output line, and its exit code.

Filter with level, which keeps that level and every more severe one, and with source, toolCallId, from, and to. limit takes 1 to 500 and defaults to 200. Every page returns nextCursor and caughtUp. When caughtUp is false, keep paging. When it is true, you have every stored line, and requesting nextCursor again later returns only the lines written since. That is how you follow a run that is still executing. A cursor works only with the filters it was issued for.

The environment's capture mode decides what a line keeps:

Capture modeMessagesAttributesHosted code output
metadata-onlyKept, with secrets redactedOnly names that do not suggest contentNot kept
redacted-contentKept, with secrets redactedAll, with secrets redactedKept
full-contentKept as writtenAll, as writtenKept

Hosted code output never contains the values of the secrets the tool declares, in any mode. Lines are bounded: a message keeps 2,000 characters, an attribute value 256, one execution of a run 1,000 lines, and one hosted code call 200 output lines. A warning line marks each cut. Lines are kept for 30 days, as long as trace spans, and erasing the thread erases them. Runtime logs do not depend on the observability hot plane, so they work on every install.

Publish automation output

Heartbeat runs, schedule runs, and runs submitted with responsePublication: "external" keep their answer provisional. The worker does not stream tokens for them, and the final message stays out of the visible history. Deliver the answer through your own channel, then record the outcome:

  1. POST /v1/threads/{threadId}/runs/{runId}/message/publication-reservations reserves the message's place in the conversation before you deliver it.
  2. POST /v1/threads/{threadId}/runs/{runId}/message/publications publishes the delivered text as a visible message.
  3. POST /v1/threads/{threadId}/runs/{runId}/message/publication-releases releases the reservation when delivery is uncertain or did not happen.

A publication moves through reserved, committed, published, and released. While a thread waits for a delivery outcome, replays on it fail with 409 publication_busy. See Schedules and heartbeats.

Continue a thread on another deployment

POST /v1/threads with continueFromThreadId starts a successor thread that carries a predecessor's conversation over to a new deployment. The successor inherits the predecessor's conversation checkpoint, and its spare history budget fills with the predecessor's recent turns. Stored messages are never copied or rewritten.

The request fails with 409 thread_continuity_mismatch in these cases:

  • The predecessor is archived.
  • The predecessor is a preview or evaluation thread.
  • The two deployments run different agent definitions.
  • The request names a different workspace than the predecessor's.

The predecessor's checkpoint must also cover its whole history. If it does not, the request fails with 409 thread_continuity_incomplete, and the platform queues the missing checkpoint work. Retry after that work completes. Set contextCheckpointMode: "auto" on releases whose threads you plan to continue.

Erase a thread or an end user

Erasure permanently deletes conversation data inside one environment. It runs in the background, and you poll the erasure until its status is completed, failed, or canceled.

ActionRouteScope
Erase a threadPOST /v1/threads/{threadId}/erasures, then GET /v1/threads/{threadId}/erasures/{erasureId}runs:erase to start, runs:read to poll
Erase an end userPOST /v1/end-users/erasures with { "endUserId": "..." }, then GET /v1/end-users/erasures/{erasureId}end-users:erase

Erasure is permanent

The thread is gone from every route as soon as the erase request returns, and it cannot be restored.

Erasing a thread deletes its messages, runs, tool calls, approvals, checkpoints, artifacts that nothing else references, the files attached to its runs or captured from its channel or email messages with the text extracted from them, memories formed in it, its schedules and heartbeats, its stream, stream sessions, channel messages staged for it, and its traces. When the thread started from agent email, it also deletes the mail of that email thread up to the erasure, received and sent, with its attachments and the drafts that answer it. The first request returns 202. A repeated request returns 200 with the same erasure. The request fails with 409 thread_active while any run of the thread is not terminal, so cancel the runs first. Preview and evaluation threads fail with 409 thread_not_erasable.

Erasing an end user erases every thread whose endUserId names that user, and cancels their active runs instead of refusing. While it runs, a repeated request returns the same erasure, and creating a thread for that end user fails with 409 end_user_erasure_in_progress. A one-to-one channel conversation, such as an SMS thread or a Slack direct message, belongs to the end user channel:{provider}:{workspace or -}:{sender}. Pass that string as endUserId to erase a channel user.

An agent email correspondent is the end user channel:email:-:{address}, with the address lowercased and percent-encoded, such as channel:email:-:alice%40example.com. Build that string yourself, or pass --email to deployments end-user erase. The route also accepts the address in any letter case. Erasing that end user deletes, up to the erasure, every email thread with a message that names the address on From, To, Cc, Bcc, or Reply-To and every draft addressed to it, including mail that never started a conversation. It also erases every thread that mail started or continued. Naming one of your own inbox addresses fails with 409 end_user_is_inbox.

The erasure reports its phase and counts, including threadsErased, runsCanceled, recordsDeleted, memoriesErased, emailMessagesErased, and emailThreadsErased. It keeps counts only. A completed end-user erasure does not hold the end user's ID or its pseudonym. Audit events, spend and meter records, and a tombstone that stops the thread ID from being reused survive. Agent email mail that arrived after the erasure was requested survives too. See Data governance.

Access

Reads need the runs:read scope and writes need runs:write. Erasing a thread needs runs:erase, and erasing an end user needs end-users:erase. A person also needs the owner or admin organization role to erase. An API key carries its own tenant, so tenant headers are optional and must match the key when you send them. A user sign-in must send x-deployments-organization, x-deployments-project, and x-deployments-environment. See Authentication.

Use it

  1. Send a message. The platform creates a thread and prints the run with its threadId.

    deployments run create --agent $AGENT_DEPLOYMENT_ID --message "Summarize yesterday's open tickets."
  2. Follow the run until it reaches a terminal status.

    deployments run tail $RUN_ID --thread $THREAD_ID --follow
  3. Read the answer, then send the next turn on the same thread.

    deployments run message $RUN_ID --thread $THREAD_ID
    deployments run create --agent $AGENT_DEPLOYMENT_ID --thread $THREAD_ID --message "Group them by owner."
  4. Find failed runs of the deployment and retry one.

    deployments run list --agent-deployment-id $AGENT_DEPLOYMENT_ID --status failed
    deployments run retry $RUN_ID
  5. Run a finished turn again as a new run, or stop a run that is still going.

    deployments run replay $RUN_ID
    deployments run cancel $RUN_ID
  6. Erase a thread, or every thread of one end user, and poll the erasure until status is completed. In a terminal the CLI asks you to confirm. In scripts or with --json, pass --yes.

    deployments thread erase $THREAD_ID
    deployments thread erasure-status $ERASURE_ID --thread $THREAD_ID
    deployments end-user erase --end-user-id "$END_USER_ID"
    deployments end-user erase --email "alice@example.com"
    deployments end-user erasure-status $ERASURE_ID

The same submission through the SDK, with a structured answer:

import { createClient, createConfig, submitAgentRun } from "@deployments-ai/sdk";

const client = createClient(
  createConfig({
    baseUrl: "https://api.example.com",
    headers: { authorization: `Bearer ${process.env.DEPLOYMENTS_API_KEY}` },
  }),
);

const { data, error } = await submitAgentRun({
  client,
  path: { agentDeploymentId: process.env.AGENT_DEPLOYMENT_ID! },
  headers: { "idempotency-key": crypto.randomUUID() },
  body: {
    content: "Classify this request: the export button is missing.",
    responseFormat: {
      type: "json_schema",
      name: "triage_result",
      schema: {
        type: "object",
        properties: {
          category: { type: "string", enum: ["billing", "bug", "other"] },
        },
        required: ["category"],
        additionalProperties: false,
      },
    },
  },
});

Reference

On this page