Create spans in a batch

client.Spans.Batch(ctx, body) (*APIListSpan, error)

POST/v5/spans/batch

Create multiple spans (up to 1000) in a single request and return the created spans.

Prefer this over repeated POST /v5/spans calls when ingesting many spans at once; use PUT /v5/spans/batch instead when a span with the same id may already exist, since this endpoint inserts new spans rather than overwriting. A batch larger than 1000 spans is rejected with a validation error. Each item follows the same id-generation and per-account dual-write rules as the single-span create, including that end_timestamp must not precede start_timestamp, which rejects the request with a 422. When the tracing service is the primary store, its 400, 413 and 422 rejections keep that status and detail, as does a 403 when the request carried its own API key, and every other failure returns a 503 with a Retry-After header. A batch that forms a cycle, or a span whose parent belongs to another trace, is rejected with 409 before either store is written. A parent outside the batch is looked up in Postgres, so that part of the check ends once the account’s spans stop being written there. Postgres rejects an id that already exists, while the tracing service treats the write as an upsert. Which writes the tracing service rejects depends in part on its storage engine: on Postgres deployments a NUL byte or invalid UTF-8 inside trace_id, id, parent_id or group_id fails the whole batch with a 400 naming the field, because replacing the byte would change the identity the response echoes; a NUL byte or invalid UTF-8 in any other field is replaced with U+FFFD and the span is persisted. ClickHouse deployments store the bytes verbatim.

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

body SpanBatchParams

SpanBatchCreate param.Field[SpanBatchCreate]

ReturnsExpand Collapse

type APIListSpan struct{…}

Items []Span

ID string

AccountID string

Name string

StartTimestamp Time

formatdate-time

TraceID string

id for grouping traces together, uuid is recommended

maxLength256

ApplicationInteractionID stringOptional

The interaction ID this span belongs to

ApplicationVariantID stringOptional

The id of the application variant this span belongs to

CreatedBy IdentityOptional

The identity that created the entity.

ID string

Type IdentityType

One of the following:

const IdentityTypeUser IdentityType = "user"

const IdentityTypeServiceAccount IdentityType = "service_account"

Object IdentityObjectOptional

EndTimestamp TimeOptional

formatdate-time

Expected map[string, any]Optional

GroupID stringOptional

Reference to a group_id

Input map[string, any]Optional

InputTokens int64Optional

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

maximum4294967295

minimum0

Metadata map[string, any]Optional

Object SpanObjectOptional

ObsSpanID stringOptional

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

ObsTraceID stringOptional

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 map[string, any]Optional

OutputTokens int64Optional

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

maximum4294967295

minimum0

ParentID stringOptional

Reference to a parent span_id

Status SpanStatusOptional

One of the following:

const SpanStatusSuccess SpanStatus = "SUCCESS"

const SpanStatusError SpanStatus = "ERROR"

const SpanStatusCanceled SpanStatus = "CANCELED"

Type SpanTypeOptional

One of the following:

const SpanTypeTextInput SpanType = "TEXT_INPUT"

const SpanTypeTextOutput SpanType = "TEXT_OUTPUT"

const SpanTypeCompletionInput SpanType = "COMPLETION_INPUT"

const SpanTypeCompletion SpanType = "COMPLETION"

const SpanTypeKBRetrieval SpanType = "KB_RETRIEVAL"

const SpanTypeKBInput SpanType = "KB_INPUT"

const SpanTypeReranking SpanType = "RERANKING"

const SpanTypeExternalEndpoint SpanType = "EXTERNAL_ENDPOINT"

const SpanTypePromptEngineering SpanType = "PROMPT_ENGINEERING"

const SpanTypeDocumentInput SpanType = "DOCUMENT_INPUT"

const SpanTypeMapReduce SpanType = "MAP_REDUCE"

const SpanTypeDocumentSearch SpanType = "DOCUMENT_SEARCH"

const SpanTypeDocumentPrompt SpanType = "DOCUMENT_PROMPT"

const SpanTypeCustom SpanType = "CUSTOM"

const SpanTypeCodeExecution SpanType = "CODE_EXECUTION"

const SpanTypeDataManipulation SpanType = "DATA_MANIPULATION"

const SpanTypeEvaluation SpanType = "EVALUATION"

const SpanTypeFileRetrieval SpanType = "FILE_RETRIEVAL"

const SpanTypeKBAddChunk SpanType = "KB_ADD_CHUNK"

const SpanTypeKBManagement SpanType = "KB_MANAGEMENT"

const SpanTypeGuardrail SpanType = "GUARDRAIL"

const SpanTypeOutputGuardrail SpanType = "OUTPUT_GUARDRAIL"

const SpanTypeTracer SpanType = "TRACER"

const SpanTypeAgentTracer SpanType = "AGENT_TRACER"

const SpanTypeAgentWorkflow SpanType = "AGENT_WORKFLOW"

const SpanTypeStandalone SpanType = "STANDALONE"

Object APIListSpanObjectOptional

Create spans in a batch

package main

import (
  "context"
  "fmt"
  "time"

  "github.com/scaleapi/sgp-dev-go"
  "github.com/scaleapi/sgp-dev-go/option"
)

func main() {
  client := sgpdev.NewClient(
    option.WithAPIKey("My API Key"),
    option.WithAccountID("My Account ID"),
  )
  apiListSpan, err := client.Spans.Batch(context.TODO(), sgpdev.SpanBatchParams{
    SpanBatchCreate: sgpdev.SpanBatchCreateParam{
      Items: []sgpdev.SpanCreateParam{sgpdev.SpanCreateParam{
        Name: "name",
        StartTimestamp: time.Now(),
        TraceID: "trace_id",
      }},
    },
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", apiListSpan.Items)
}

{
  "items": [
    {
      "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"
    }
  ],
  "object": "list"
}

Returns Examples

{
  "items": [
    {
      "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"
    }
  ],
  "object": "list"
}