---
title: "Admit events [trace grant]"
method: POST
path: "/traces/{id}/events"
tags: ["traces"]
---

# Admit events \[trace grant\]

`POST /traces/{id}/events`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/traces/{id}/events`
- Auth: HTTP bearer

Authenticated by a trace grant token (Bearer tgr_…), not an API key. At most 256 events, 64 KiB each, 4 MiB per request. Each event is judged on its own: the same event id and content returns its first receipt; different content, a session outside the workspace, another source's span, a changed parent, a parent cycle or content outside the grant's scopes is refused. Returns 404 when the TASK_TRACES switch is off for the workspace and 503 not_migrated before the tables exist.

## Path parameters

- `id` string, required

## Request body

- object
  - `events` TaskTraceEvent[], required
    - `event_id` string, required: Unique per source; resending the same event returns its first receipt
    - `sequence` integer, required: Order within the source
    - `span_id` string, required
    - `parent_span_id` string, nullable: Set once, by the span's first event; a different parent later is refused
    - `kind` 'start' | 'end' | 'event', required
    - `name` string
    - `outcome` 'running' | 'completed' | 'failed' | 'cancelled' | 'unknown'
    - `coverage` 'complete' | 'partial' | 'redacted' | 'metadata_only'
    - `session_id` string: A session of the trace's workspace (sess_…)
    - `task_id` string: A task of the trace's workspace (its root session id)
    - `source_time` string, date-time: The source's clock; informative only
    - `attributes` object
    - `content` object: Only in a scope the grant names. Redacted again on arrival: a credential-shaped value is replaced and the event reads `redacted`; text that cannot be redacted is not kept and the event reads `metadata_only`.
      - `scope` 'prompts' | 'tool_output' | 'files', required
      - `text` string, required: At most 48 KiB (UTF-8)
      - `path` string: For files, and only for files
      - `truncated` boolean: The source cut the text to fit
      - `redactions` integer: Values the source already replaced

## Response `200`

OK

- object
  - `trace_id` string, required
  - `source` string, required
  - `results` TaskTraceEventResult[], required
    - `event_id` string, required
    - `status` 'admitted' | 'duplicate' | 'refused', required
    - `receipt` string
    - `received_at` string, date-time
    - `code` 'event_conflict' | 'foreign_reference' | 'span_owned' | 'parent_changed' | 'parent_cycle' | 'content_not_granted'
    - `message` string

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/traces/:id/events/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)