Run reports

Every persisted assistant response can send one run report to Assistant Cloud. The report records the response, model work, tools, timing, deployment dimensions, and errors. A report the SDK builds carries the assistant's text and the tool arguments and results, never the user's messages. A report you send yourself can add steps[].input, which stores whatever you put there, a user's prompt included. The dashboard turns that record into the Runs, Models, Users, and Overview views.

Reports can contain assistant text, tool arguments and results, step input and error text, and tool arguments often quote the user. Use beforeReport to remove or redact those values before they leave the app, or turn telemetry off when the project should store threads and messages without reports or engagement events.

What a report accepts

cloud.runs.report() sends POST /v1/runs. thread_id and status are required. Every other field is optional, but the endpoint validates its type and bound before it writes the run.

Step fields

Each steps item may include the following fields. Step usage has the same integer 0 to 100,000,000 bound as run usage.

Tool call fields

Each tool_calls item has a required name. The service generates tool_call_id when it is omitted.

Each sampling_calls item may have model_id of up to 255 characters, the four usage counters from 0 to 100,000,000, and duration_ms as an integer of 0 or more.

Attributes and size limits

The service combines metadata, unknown top level keys, and attributes in that order. Later attributes values win. The resulting attributes JSON must be at most 16,384 bytes. Unknown top level keys are kept as attributes instead of being rejected, so a newer SDK can send fields an older project does not yet recognize.

The route rejects invalid input with the validation response shape { "success": false, "error": "…" }. It also returns { "error": "message_id must belong to thread_id" } when the message is not in the named thread, and { "error": "Thread not found" } when the thread is not visible to the caller.

How the SDK builds a report

The thread history adapter reports a terminal assistant message after persistence. It combines the message derived state with the extracted format data, resolves the remote message id, and sends the resulting report. A message derived status and outcome take precedence over values extracted from the stored format.

For both message formats, report construction reads only assistant messages. A message waiting for tool approval is not reported, so a paused run is not counted as completed or reported twice.

messageMetadata values

An AI SDK route must return server values through messageMetadata. The client cannot infer model, provider, usage, or trace id from the browser stream. The whole route, with the callback that fills the report:

import { convertToModelMessages, streamText } from "ai";
import { openai } from "@ai-sdk/openai";

export async function POST(req: Request) {
  const { messages } = await req.json();
  const model = openai("gpt-5.6-luna");
  const result = streamText({
    model,
    messages: await convertToModelMessages(messages),
  });

  return result.toUIMessageStreamResponse({
    messageMetadata: ({ part }) => {
      if (part.type === "finish") {
        return { usage: part.totalUsage, finishReason: part.finishReason };
      }
      if (part.type === "finish-step") {
        return { modelId: part.response.modelId, provider: model.provider };
      }
      return undefined;
    },
  });
}

Each key the callback returns maps to a report field:

The docs chat route illustrates the handoff. It adds modelId at finish-step, adds usage at finish, and wraps that callback with withAssistantCloudTraceMetadata so the start part carries traceId.

How status and outcome are derived

The SDK derives a status before it creates the report. The first matching input wins: isError, then isAbort, then isDisconnect, then finishReason. With no matching input, the fallback status is completed.

The Overview outcome chart groups values differently from the report vocabulary: completed, stopped for aborted, disconnected, truncated for length or content_filter, failed for every other outcome type, and unknown when there is no outcome type.

Normalization and delivery

createRunReport converts the runtime shaped input into the wire shape. It lowercases traceId and keeps it only when it is exactly 32 lowercase hexadecimal characters. It writes the provider to both provider and the legacy provider_type field, converts camel case fields to their wire names, makes total_steps equal steps.length when steps are present, and rounds finite timing values to the nearest nonnegative integer. Nonfinite timing values are omitted.

outputText is truncated at 50,000 characters. A message derived error is truncated at 2,048 characters and its code at 64 characters. A directly supplied report must still meet the route's 2,048 character error bound. Tags are trimmed, limited to 64 characters, deduplicated, and capped at 20. Empty usage stays absent rather than becoming four zeroes.

CloudRunReporter follows one delivery order:

1. Return when telemetry is disabled or a supplied deduplication key was already sent.
2. Build and normalize the report with the cloud telemetry configuration.
3. Call beforeReport last. A returned null skips the request before claiming the deduplication key. A thrown callback is swallowed.
4. Claim the key, when one was supplied, then send the report.

The reporter swallows send failures. It releases a claimed key only after a 429 response, so a later observation may send that report again. It does not retry any other failure, and the standard thread history path supplies no key.

Deployment dimensions and clients

environment, release, and tags in the telemetry configuration are stamped on each client report. They become Run facets. release is your application version, not an SDK version.

const cloud = new AssistantCloud({
  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
  anonymous: true,
  telemetry: {
    environment: "production",
    release: "2026.09.1",
    tags: ["web", "eu"],
  },
});

Every request also sends Aui-Sdk. It begins with assistant-cloud/<version>, followed by registered integration identities in registration order. The cloud records at most 8 header tokens, names of at most 214 characters, and versions of at most 64 characters.

Settings › Telemetry lists those client names and versions, newest first, with the last time each was seen. A client entry is recorded at most once in 10 minutes and retained for 180 days. The page also gives the project API URL, the trace receiver URL, and the trace link template that turns a run's trace id into a link to your observability system.

When a client report meets server spans

A report with a valid W3C trace_id locks and merges into the existing run for the same project and trace id. Either side may arrive first.

The merge replays the daily run rollup when a changed field affects it.

What the dashboard derives

The Runs page has Status, Source, Reason, Model, Environment, Release, Agent, Service, Tag, Cost, and Duration facets. Its table shows status, model, user, environment, release, tokens, cost, duration, and creation time. The tiles show Runs, Incomplete, Cost, p95 duration, and First token p50. Search matches a run id, thread id, user, error, or error code.

The analysis view applies the same filters to latency percentiles, duration distributions and heatmaps, a run sample, tool statistics, release statistics, and model statistics. The run detail view shows outcome, source, thread, user, message, assistant, deployment fields, timing, usage, attributes, scores, and a span waterfall with the selected span's arguments or prompt.

Models are grouped by catalog model and provider, while retaining the reported model ids as variants. A model row includes runs, sampled runs, incomplete runs, all four token counters, cost, priced and unpriced run counts, and latency percentiles. Its Price section shows the model it was priced as and input, cached input, and output prices. A run with no model_id cannot name a model in this view or be catalog priced.

Redact, drop, or turn telemetry off

beforeReport receives the fully assembled report. Return a replacement report to redact data or add attributes. Return null to skip it.

const cloud = new AssistantCloud({
  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
  authToken: getToken,
  telemetry: {
    beforeReport: (report) => {
      if (report.thread_id === internalTestThread) return null;
      return { ...report, metadata: { ...report.metadata, plan: "pro" } };
    },
  },
});

Troubleshooting