---
title: "Ingest Events"
method: POST
path: "/api/v1/telemetry/events"
tags: ["telemetry"]
---

# Ingest Events

`POST /api/v1/telemetry/events`

## Headers

- `X-API-Key` string, required

## Request body

- TelemetryEventsIngestRequest
  - `events` TelemetryEventIngestRequest[], required — Telemetry events to ingest.
    - `event_id` string, required — Caller-provided unique event id used for idempotency and deduplication.
    - `event_type` string, required — Product-defined telemetry event name, such as 'tool_call' or 'user_accept'.
    - `timestamp` string, required — ISO 8601 timestamp for when the event occurred.
    - `session_id` string, required — Grouping key for a broader user session, eval run, or import job.
    - `source` string, required — Origin of the event, such as 'sdk', 'api', 'training', or 'synthetic'.
    - `user_id` string, nullable — End-user identifier from the caller's system, when available.
    - `trajectory_id` string, nullable — Stored trajectory id returned by trajectory upload, when already known.
    - `trace_id` string, nullable — Caller-owned correlation key shared by telemetry and its trajectory.
    - `properties` object — Event-specific JSON properties.
    - `metadata` object, nullable — Additional metadata for debugging, SDK versions, or ingestion context.

## Response `200`

Successful Response

- TelemetryEventsIngestResponse
  - `ingested` integer, required — Number of telemetry events accepted for ingestion.
  - `skipped` integer — Number of telemetry events skipped by validation.
  - `failures` BatchItemFailure[] — Structured batch-level ingestion failures, if any.
    - `code` string, required — Stable programmatic reason for this item failure.
    - `message` string, required — Human-readable explanation for this item occurrence.
    - `item_index` integer, nullable — Zero-based input index when the failed item came from a list.
    - `context` object — Machine-readable values specific to this failure code.

## Other responses

- `207` — Some telemetry event batches were accepted, but one or more failed.

---

[API](https://skmtc.dev/trajectory/apis/trajectory-api.md) · [All operations](https://skmtc.dev/trajectory/apis/trajectory-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trajectory/trajectory-api/revisions/d930b23b9602/schema)