Skip to main content

W3C Trace Context Validator API

REAL DATA

Validate and explain W3C traceparent and tracestate values, including versioning, zero-ID checks, sampled flags and vendor-entry grammar.

Authoritative reference data or standards computation

Base URL
/api/trace-context
Category
Developer Tools
Capabilities
1 route
Last updated
July 29, 2026
Data source

GET /api/trace-context/validate Validate traceparent and optional tracestate field values

Live requestRuns against the public API
No key required
GET/api/trace-context/validate?traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01&tracestate=rojo%3D00f067aa0ba902b7%2Ccongo%3Dt61rcWkgMzE

Request parameters

Raw traceparent field value, bounded to 512 characters. Lowercase hexadecimal is required.

Optional combined tracestate value; this endpoint caps input at 2048 characters and 32 list-members.

Advanced response options4 options

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/trace-context/validate?traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01&tracestate=rojo%3D00f067aa0ba902b7%2Ccongo%3Dt61rcWkgMzE"
const res = await fetch("https://randomapi.dev/api/trace-context/validate?traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01&tracestate=rojo%3D00f067aa0ba902b7%2Ccongo%3Dt61rcWkgMzE");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/trace-context/validate?traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01&tracestate=rojo%3D00f067aa0ba902b7%2Ccongo%3Dt61rcWkgMzE").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/trace-context/validate?traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01&tracestate=rojo%3D00f067aa0ba902b7%2Ccongo%3Dt61rcWkgMzE"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 2
traceparent string required

Raw traceparent field value, bounded to 512 characters. Lowercase hexadecimal is required.

allowed: 1 – 512
example: traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate string

Optional combined tracestate value; this endpoint caps input at 2048 characters and 32 list-members.

allowed: ≤ 2048
example: tracestate=rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
Universal parameters Shared response and formatting options 4
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=valid,traceparentValid
exclude list

Return all fields except these (comma-separated).

example: exclude=warnings
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 15
valid boolean

Whether traceparent and any supplied tracestate are both valid.

example: true

traceparentValid boolean

Whether the traceparent common fields and version rules are valid.

example: true

tracestateValid boolean nullable

Whether supplied tracestate is valid; null when absent or skipped after bad traceparent.

example: true

version string nullable

Two-character lowercase version when its prefix could be parsed.

example: 00

traceId string nullable

32-character nonzero trace ID when valid.

example: 4bf92f3577b34da6a3ce929d0e0e4736

parentId string nullable

16-character nonzero parent ID when valid.

example: 00f067aa0ba902b7

traceFlags string nullable

Two-character received flags byte when valid.

example: 01

sampled boolean nullable

Whether the least-significant sampled flag is set.

example: true

unknownFlags string nullable

Hex mask for every received flag bit not defined by Trace Context 1.1.

example: 00

futureVersion boolean nullable

Whether the parsed version is higher than 00.

example: false

tracestateEntries object[]

Valid vendor entries in received order; empty when absent, invalid or skipped.

example: [{"key":"rojo","value":"00f067aa0ba902b7","index":0}]

canonicalTraceparent string nullable

Validated traceparent, or null when invalid.

example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

canonicalTracestate string nullable

Whitespace-normalized valid tracestate, or null when absent/invalid/skipped.

example: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

errors object[]

Ordered validation failures with code, field and message.

example: []

warnings object[]

Non-fatal notices such as unknown flag bits or skipped tracestate.

example: []

Documented examples

Build-generated requests and complete responses 3
Validate sampled W3C context with two vendors
GET /api/trace-context/validate?traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01&tracestate=rojo%3D00f067aa0ba902b7%2Ccongo%3Dt61rcWkgMzE 
{
  "data": {
    "valid": true,
    "traceparentValid": true,
    "tracestateValid": true,
    "version": "00",
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "parentId": "00f067aa0ba902b7",
    "traceFlags": "01",
    "sampled": true,
    "unknownFlags": "00",
    "futureVersion": false,
    "tracestateEntries": [
      {
        "key": "rojo",
        "value": "00f067aa0ba902b7",
        "index": 0
      },
      {
        "key": "congo",
        "value": "t61rcWkgMzE",
        "index": 1
      }
    ],
    "canonicalTraceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
    "canonicalTracestate": "rojo=00f067aa0ba902b7,congo=t61rcWkgMzE",
    "errors": [],
    "warnings": []
  },
  "meta": {
    "endpoint": "trace-context",
    "route": "/validate",
    "params": {
      "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
      "tracestate": "rojo=00f067aa0ba902b7,congo=t61rcWkgMzE"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Validate an unsampled context without tracestate
GET /api/trace-context/validate?traceparent=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00 
{
  "data": {
    "valid": true,
    "traceparentValid": true,
    "tracestateValid": null,
    "version": "00",
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "parentId": "00f067aa0ba902b7",
    "traceFlags": "00",
    "sampled": false,
    "unknownFlags": "00",
    "futureVersion": false,
    "tracestateEntries": [],
    "canonicalTraceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00",
    "canonicalTracestate": null,
    "errors": [],
    "warnings": []
  },
  "meta": {
    "endpoint": "trace-context",
    "route": "/validate",
    "params": {
      "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Inspect a forward-compatible version
GET /api/trace-context/validate?traceparent=01-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01-extra 
{
  "data": {
    "valid": true,
    "traceparentValid": true,
    "tracestateValid": null,
    "version": "01",
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "parentId": "00f067aa0ba902b7",
    "traceFlags": "01",
    "sampled": true,
    "unknownFlags": "00",
    "futureVersion": true,
    "tracestateEntries": [],
    "canonicalTraceparent": "01-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01-extra",
    "canonicalTracestate": null,
    "errors": [],
    "warnings": []
  },
  "meta": {
    "endpoint": "trace-context",
    "route": "/validate",
    "params": {
      "traceparent": "01-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01-extra"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Validates the two interoperable HTTP field values defined by the W3C Trace Context Recommendation. traceparent is decomposed into its version, 16-byte trace ID, 8-byte parent ID and flags; the sampled bit is reported separately while unknown received bits are preserved and warned about rather than reinterpreted.

Version 00 must be exactly 55 lowercase characters. The forbidden ff version, uppercase hexadecimal, malformed delimiters and all-zero IDs are invalid. Higher versions follow W3C's forward-compatible common-prefix rules: the version-00 fields are parsed, extension data is left opaque and no future semantics are invented.

When supplied, tracestate is parsed only after a valid traceparent, just as the processing model requires. It accepts at most 32 list-members, supports simple and multi-tenant keys, rejects duplicate keys, and validates each opaque value's printable-ASCII bounds. Empty list-members are accepted but omitted from canonical output.

Ordinary invalid header values return 200 with valid:false and ordered reason codes, making the endpoint useful in test suites. The query parser still returns 400 for a missing required parameter or values beyond the endpoint's explicit resource bounds. This API validates syntax and interoperable field semantics; it does not contact a tracing backend or prove that a trace exists.

Use it for

  • Validate incoming traceparent headers before propagating distributed trace context
  • Explain why two services fail to join the same trace
  • Test sampled-flag and future-version behavior with deterministic fixtures
  • Audit tracestate vendor keys, duplicates and entry-count limits

Frequently asked questions

Practical answers about this endpoint 4
What makes a traceparent value invalid?

Common failures include uppercase hexadecimal, a forbidden ff version, wrong field lengths or delimiters, and all-zero trace or parent IDs.

Does the API support future traceparent versions?

Yes. It validates the common prefix required by W3C, marks the version as future, and deliberately leaves extension fields opaque instead of guessing their meaning.

How is tracestate validated?

Only after traceparent succeeds. The validator enforces the 32-member limit, key grammar, unique keys and bounded printable-ASCII values while preserving vendor order.

Does a valid result prove the trace exists?

No. It proves only that the supplied field values follow W3C Trace Context syntax and shared semantics; no collector or vendor backend is queried.

Standards & references

Primary sources behind the contract

Related APIs

Useful next tools in the catalog
Mock Distributed Trace and Span API MOCK DATA

Generate coherent mock distributed traces and individual spans with bounded timing, parentage, service filters and reproducible failures.
HTTP Field Name Registry API REAL DATA

Complete pinned IANA HTTP field-name registry with status, Structured Field type, references, search and case-insensitive lookup.
Fake Audit Log API MOCK DATA

Generate coherent fake audit records for authentication, CRUD and permission changes — safely seeded, filterable and bounded by time.
Fake Webhook Delivery API MOCK DATA

Generate coherent webhook delivery histories with safe destinations, bounded retries, status-specific attempts and event-shaped payloads.
CloudEvents 1.0 Mock Data API MOCK DATA

Generate coherent mock CloudEvents 1.0 structured JSON envelopes with all required context attributes and action-specific event data.