Update a span

client.spans.update(, , ?): Span { id, account_id, name, 19 more }

PATCH/v5/spans/{span_id}

Partially update a span’s mutable fields and return the updated span.

Only the provided fields among name, end timestamp, output, metadata, and status are changed. This endpoint is available only for accounts still served solely by the legacy trace store: once an account begins dual-writing to the tracing service — which is upsert-only and has no partial-update operation — PATCH returns 501 and PUT /v5/spans/batch must be used instead. Updates are authorized against the span’s parent trace, and an unknown id returns 404.

Credential redaction: values in the free-form input, output, metadata, and expected objects, and in name, that are credential-shaped (bearer/JWT, API keys, connection-string passwords) or under a credential-named key are replaced with [REDACTED:credential] before the span is persisted, so the stored and returned span reflects the redacted value (EY 12.3).

ParametersExpand Collapse

spanID: string

body: SpanUpdateParams { end_timestamp, metadata, name, 2 more }

end_timestamp?: string

formatdate-time

metadata?: Record<string, unknown>

name?: string

output?: Record<string, unknown>

status?: SpanStatus

One of the following:

"SUCCESS"

"ERROR"

"CANCELED"

ReturnsExpand Collapse

Span { id, account_id, name, 19 more }

id: string

account_id: string

name: string

start_timestamp: string

formatdate-time

trace_id: string

id for grouping traces together, uuid is recommended

maxLength256

application_interaction_id?: string

The interaction ID this span belongs to

application_variant_id?: string

The id of the application variant this span belongs to

created_by?: Identity { id, type, object }

The identity that created the entity.

id: string

type: "user" | "service_account"

One of the following:

"user"

"service_account"

object?: "identity"

end_timestamp?: string

formatdate-time

expected?: Record<string, unknown>

group_id?: string

Reference to a group_id

input?: Record<string, unknown>

input_tokens?: number

Prompt tokens the producer reported for this span, absent when it reported none. Same quantity the input_tokens sort orders by.

maximum4294967295

minimum0

metadata?: Record<string, unknown>

object?: "span"

obs_span_id?: string

W3C span id of the observability span this span executed in.

obs_trace_id?: string

W3C trace id of the observability trace this span executed in. Null for spans written without the edge, and for accounts still served by the legacy trace store.

output?: Record<string, unknown>

output_tokens?: number

Completion tokens the producer reported for this span, absent when it reported none. Same quantity the output_tokens sort orders by.

maximum4294967295

minimum0

parent_id?: string

Reference to a parent span_id

status?: SpanStatus

One of the following:

"SUCCESS"

"ERROR"

"CANCELED"

type?: SpanType

One of the following:

"TEXT_INPUT"

"TEXT_OUTPUT"

"COMPLETION_INPUT"

"COMPLETION"

"KB_RETRIEVAL"

"KB_INPUT"

"RERANKING"

"EXTERNAL_ENDPOINT"

"PROMPT_ENGINEERING"

"DOCUMENT_INPUT"

"MAP_REDUCE"

"DOCUMENT_SEARCH"

"DOCUMENT_PROMPT"

"CUSTOM"

"CODE_EXECUTION"

"DATA_MANIPULATION"

"EVALUATION"

"FILE_RETRIEVAL"

"KB_ADD_CHUNK"

"KB_MANAGEMENT"

"GUARDRAIL"

"OUTPUT_GUARDRAIL"

"TRACER"

"AGENT_TRACER"

"AGENT_WORKFLOW"

"STANDALONE"

Update a span

import SGPClient from 'scale-gp';

const client = new SGPClient({
  accountID: 'My Account ID',
  apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted
});

const span = await client.spans.update('span_id');

console.log(span.id);

{
  "id": "id",
  "account_id": "account_id",
  "name": "name",
  "start_timestamp": "2019-12-27T18:11:19.117Z",
  "trace_id": "trace_id",
  "application_interaction_id": "application_interaction_id",
  "application_variant_id": "application_variant_id",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "end_timestamp": "2019-12-27T18:11:19.117Z",
  "expected": {
    "foo": "bar"
  },
  "group_id": "group_id",
  "input": {
    "foo": "bar"
  },
  "input_tokens": 0,
  "metadata": {
    "foo": "bar"
  },
  "object": "span",
  "obs_span_id": "obs_span_id",
  "obs_trace_id": "obs_trace_id",
  "output": {
    "foo": "bar"
  },
  "output_tokens": 0,
  "parent_id": "parent_id",
  "status": "SUCCESS",
  "type": "TEXT_INPUT"
}

Returns Examples

{
  "id": "id",
  "account_id": "account_id",
  "name": "name",
  "start_timestamp": "2019-12-27T18:11:19.117Z",
  "trace_id": "trace_id",
  "application_interaction_id": "application_interaction_id",
  "application_variant_id": "application_variant_id",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "end_timestamp": "2019-12-27T18:11:19.117Z",
  "expected": {
    "foo": "bar"
  },
  "group_id": "group_id",
  "input": {
    "foo": "bar"
  },
  "input_tokens": 0,
  "metadata": {
    "foo": "bar"
  },
  "object": "span",
  "obs_span_id": "obs_span_id",
  "obs_trace_id": "obs_trace_id",
  "output": {
    "foo": "bar"
  },
  "output_tokens": 0,
  "parent_id": "parent_id",
  "status": "SUCCESS",
  "type": "TEXT_INPUT"
}