---
title: "Create Span"
method: POST
path: "/span"
tags: ["Span"]
---

# Create Span

`POST /span`

## Request

- Base URL: `https://oneuptime.com/api`
- URL: `https://oneuptime.com/api/span`
- Auth: API key in header `APIKey`
- TypeScript: <https://skmtc.dev/oneuptime/apis/oneuptime-openapi-specification/docs/span/post.ts> (a function with typed inputs; its response is checked against the schema)

Endpoint to create a new Span

## Request body

- object
  - `data` SpanItemV3CreateSchema, required: Create schema for SpanItemV3
    - `projectId` string, uuid: ID of project
    - `primaryEntityId` string, uuid, required: ID of the resource the span belongs to (Service / Host / DockerHost / KubernetesCluster / Monitor — disambiguated by primaryEntityType)
    - `primaryEntityType` string: Discriminator for primaryEntityId — tells the read side which resource table to dispatch to
    - `startTime` string, date-time, required: When did the span start?
    - `endTime` string, date-time, required: When did the span end?
    - `startTimeUnixNano` union, required: When did the span start?
      - number
      - string
    - `durationUnixNano` number, required: How long did the span last?
    - `endTimeUnixNano` union, required: When did the span end?
      - number
      - string
    - `traceId` string, required: ID of the trace
    - `spanId` string, required: ID of the span
    - `sessionId` string: Session replay session ID that produced this span; '' when the span has no browser session in context.
    - `parentSpanId` string: ID of the parent span
    - `traceState` string: Trace State
    - `attributes` object: Attributes
    - `attributeKeys` string[]: Attribute keys extracted from attributes
    - `entityKeys` string[]: Stable keys of every OpenTelemetry entity (service, host, k8s.pod, container, ...) this signal belongs to. A superset that includes the primary entity. Enables cross-cutting membership queries via has(entityKeys, :key).
    - `serviceEntityKey` string: Scalar entity key for this entity type (see entityKeys); '' when the resource has no entity of this type.
    - `hostEntityKey` string: Scalar entity key for this entity type (see entityKeys); '' when the resource has no entity of this type.
    - `k8sPodEntityKey` string: Scalar entity key for this entity type (see entityKeys); '' when the resource has no entity of this type.
    - `k8sNodeEntityKey` string: Scalar entity key for this entity type (see entityKeys); '' when the resource has no entity of this type.
    - `k8sClusterEntityKey` string: Scalar entity key for this entity type (see entityKeys); '' when the resource has no entity of this type.
    - `containerEntityKey` string: Scalar entity key for this entity type (see entityKeys); '' when the resource has no entity of this type.
    - `events` object[]: Span Events
    - `links` unknown
    - `statusCode` number: Status Code
    - `statusMessage` string: Status Message
    - `name` string: Name of the span
    - `kind` string: Kind of the span
    - `hasException` boolean: Whether this span contains an exception event, populated at ingest time for fast error filtering
    - `isRootSpan` boolean: Whether this span is a root span (has no parent), populated at ingest time for fast root-only filtering
    - `isEntrySpan` boolean: Whether work enters a service at this span (a root span, or a SERVER or CONSUMER span), populated at ingest time for fast entry-span filtering
    - `isLlmSpan` boolean: Whether this span is an LLM / GenAI / AI-agent operation, populated at ingest time for fast filtering of AI calls
    - `llmSystem` string: GenAI provider / system, e.g. openai, anthropic, aws.bedrock (gen_ai.system)
    - `llmOperation` string: GenAI operation, e.g. chat, embeddings, execute_tool, invoke_agent (gen_ai.operation.name)
    - `llmRequestModel` string: Model requested by the caller (gen_ai.request.model)
    - `llmResponseModel` string: Model the provider actually served (gen_ai.response.model)
    - `llmAgentName` string: Name of the agent for agent-framework spans (gen_ai.agent.name)
    - `llmToolName` string: Name of the tool invoked for tool-call spans (gen_ai.tool.name)
    - `llmInputTokens` number: Input/prompt token count (gen_ai.usage.input_tokens)
    - `llmOutputTokens` number: Output/completion token count (gen_ai.usage.output_tokens)
    - `llmTotalTokens` number: Total token count (gen_ai.usage.total_tokens, or input + output)
    - `llmCost` number: Cost of this LLM call in USD. The instrumentation-reported cost (gen_ai.usage.cost) when present; otherwise estimated at ingest from token counts and the built-in model price catalog (Common/Types/Telemetry/LlmCostCatalog.ts). 0 when neither is available.
    - `llmConversationId` string: Conversation / session id that groups the LLM calls of one user interaction across traces (gen_ai.conversation.id, session.id); '' when the instrumentation reports none.
    - `llmUserId` string: Id of the employee / internal actor who made this LLM call (user.id, enduser.id, or the gateway / coding-agent equivalent). NOT the caller's own downstream customer — that identity is deliberately never mapped here. '' when the instrumentation reports none.
    - `llmUserEmail` string: Email of the employee / internal actor who made this LLM call (user.email, emitted natively by Claude Code, Gemini CLI and Codex). Subject to the project's Attributes-scoped trace scrub rules. '' when the instrumentation reports none.
    - `llmTeam` string: Team / cost centre the LLM spend charges to (team.id, cost_center, department — conventionally set via OTEL_RESOURCE_ATTRIBUTES). '' when none is reported.
    - `llmCallKind` string: What the AI call did: answer (a model generating a response), agent, tool, embedding, retrieval or other. '' on calls ingested before this column existed.
    - `llmIssues` string[]: What went wrong with the AI call's answer: failed, refused, cut_off, empty or flagged (by an evaluation the app sent). Empty when nothing did.
    - `llmUserMessagePreview` string: The first 300 characters of the newest message the person sent in this AI call, read after the project's scrub rules, so conversations can be listed under and searched by what was asked. '' when the prompt was not recorded.

## Response `201`

Created successfully

- object
  - `data` SpanItemV3ReadSchema
    - `projectId` string, required: Project ID
    - `primaryEntityId` string, required: Service ID
    - `primaryEntityType` string: Service Type
    - `startTime` string: Start Time
    - `endTime` string: End Time
    - `startTimeUnixNano` string: Start Time in Unix Nano
    - `durationUnixNano` number, required: Duration in Unix Nano
    - `endTimeUnixNano` string: End Time
    - `traceId` string, required: Trace ID
    - `spanId` string, required: Span ID
    - `sessionId` string: Session ID
    - `parentSpanId` string: Parent Span ID
    - `traceState` string: Trace State
    - `attributes` string: Attributes
    - `attributeKeys` string[]: Attribute Keys
    - `entityKeys` string[]: Entity Keys
    - `serviceEntityKey` string: Service Entity Key
    - `hostEntityKey` string: Host Entity Key
    - `k8sPodEntityKey` string: Kubernetes Pod Entity Key
    - `k8sNodeEntityKey` string: Kubernetes Node Entity Key
    - `k8sClusterEntityKey` string: Kubernetes Cluster Entity Key
    - `containerEntityKey` string: Container Entity Key
    - `events` object[]: Events
    - `links` object: Links
    - `statusCode` number: Status Code
    - `statusMessage` string: Status Message
    - `name` string: Name
    - `kind` string: Kind
    - `hasException` boolean: Has Exception
    - `isRootSpan` boolean: Is Root Span
    - `isEntrySpan` boolean: Is Entry Span
    - `isLlmSpan` boolean: Is LLM Span
    - `llmSystem` string: LLM System
    - `llmOperation` string: LLM Operation
    - `llmRequestModel` string: LLM Request Model
    - `llmResponseModel` string: LLM Response Model
    - `llmAgentName` string: LLM Agent Name
    - `llmToolName` string: LLM Tool Name
    - `llmInputTokens` number: LLM Input Tokens
    - `llmOutputTokens` number: LLM Output Tokens
    - `llmTotalTokens` number: LLM Total Tokens
    - `llmCost` number: LLM Cost (USD)
    - `llmConversationId` string: LLM Conversation ID
    - `llmUserId` string: LLM User ID
    - `llmUserEmail` string: LLM User Email
    - `llmTeam` string: LLM Team
    - `llmCallKind` string: LLM Call Kind
    - `llmIssues` string[]: LLM Answer Issues
    - `llmUserMessagePreview` string: LLM User Message Preview

## Other responses

- `400`: Bad request. This response indicates that the request was malformed or contained invalid data.
- `401`: Unauthorized. This response indicates that the request requires user authentication.
- `402`: Payment Required. This response indicates that the request requires payment or a valid subscription.
- `403`: Forbidden. This response indicates that the server understood the request, but refuses to authorize it.
- `405`: Project not found. This response indicates that the requested project does not exist or is not accessible.
- `408`: Request Timeout. This response indicates that the server timed out waiting for the request.
- `415`: Unable to reach server. This response indicates that the server is currently unreachable or down.
- `422`: Not authorized. This response indicates that the user does not have permission to access the requested resource.
- `500`: Internal Server Error. This response indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

---

[API](https://skmtc.dev/oneuptime/apis/oneuptime-openapi-specification.md) - [All operations](https://skmtc.dev/oneuptime/apis/oneuptime-openapi-specification/llms.txt) - [OpenAPI document](https://skmtc.dev/oneuptime/apis/oneuptime-openapi-specification/revisions/ba3307d00304?raw)