Record events

Use POST /openapi/v1/events/batch to record one to 100 events. The complete request body must be no larger than 1 MiB, and each payload must be no larger than 256 KiB after JSON encoding.

Event fields

Field	Type	Required	Description
`eventId`	string	Yes	Idempotency key. Keep it unchanged across retries. Maximum 160 characters.
`clientId`	string	Yes	Stable identifier for your SDK installation or process family. Maximum 120 characters.
`runId`	string	Yes	One agent execution. Maximum 255 characters.
`sessionId`	string	No	Groups related runs, such as one conversation.
`agentId`	string	No	Stable external agent identifier.
`agentName`	string	Yes	Human-readable agent name.
`eventType`	string	Yes	Event category. Maximum 50 characters.
`label`	string	Yes	Short timeline label. Maximum 255 characters.
`timestamp`	integer	Yes	Unix time in milliseconds.
`payload`	object	No	Event-specific data. Defaults to `{}`.
`schemaVersion`	string	No	Event wire-contract version. Use `1.0`. The legacy value `1` is accepted and normalized to `1.0`.

timestamp can be at most 30 days old and up to five minutes in the future. If schemaVersion is omitted, the server stores the event as 1.0. Unknown versions are rejected at request validation so an incompatible payload is not silently misread. The optional workspaceId field is only a consistency hint. If it differs from the workspace selected by the API key, the event is rejected.

Example batch

[
  {
    "eventId": "evt_llm_01",
    "clientId": "go-service",
    "runId": "run_checkout_938",
    "sessionId": "session_user_42",
    "agentId": "checkout-agent",
    "agentName": "checkout-agent",
    "eventType": "LLM_CALL",
    "label": "Choose payment action",
    "schemaVersion": "1.0",
    "timestamp": 1784808000000,
    "payload": {
      "model": "model-name",
      "latency": 420,
      "cost": 0.0021,
      "usage": {
        "promptTokens": 240,
        "completionTokens": 32,
        "totalTokens": 272
      }
    }
  }
]

Use the same runId for every event in one execution. Use the same sessionId across related executions.

Partial success response

{
  "success": false,
  "accepted": 1,
  "retryableEventIds": ["evt_tool_02"],
  "rejectedEventIds": ["evt_invalid_03"]
}

The server evaluates each event independently:

Remove accepted events from the local queue.
Retry only IDs in retryableEventIds.
Permanently remove IDs in rejectedEventIds and record a local diagnostic.
Treat a repeated, already stored eventId as accepted.

Do not retry the entire original batch without filtering it. Doing so wastes capacity even though repeated IDs are idempotent.

Suggested event order

A language SDK can start with these practical event types:

USER_INPUT
AGENT_STEP
LLM_CALL
TOOL_CALL
POLICY_DECISION
PROMPT_EXPOSURE
ERROR
SESSION_OUTCOME

SESSION_OUTCOME closes the Run. Put COMPLETED, FAILED, or CANCELLED in payload.status. Emit PROMPT_EXPOSURE once when a Run first uses a variant from an active prompt experiment. Also attach the same promptExposures array to SESSION_OUTCOME as a delivery fallback:

{
  "promptExposures": [
    {
      "experimentId": "a247c152-3277-4c91-9b22-95cb7a459d1e",
      "promptId": "72adbb57-96ad-4d3d-a2dc-8faf071673e5",
      "promptVersionId": "c1821bc3-bf1e-46ef-b210-b9376a41cd0c",
      "bucket": 42,
      "runtimeConfigRevision": "revision-1"
    }
  ]
}

Do not send the raw assignment key. The server verifies the experiment, variant, environment, and Agent scope before storing the exposure. Lynx accepts other event type strings, but a stable shared vocabulary makes dashboards and debugging more useful.

In metadata-only mode, omit prompt text, model output, and tool arguments. In every mode, mask credentials and personal data before creating the event.

Getting started

TypeScript SDK

OpenAPI

Record events

Event fields

Example batch

Partial success response

Suggested event order

​Event fields

​Example batch

​Partial success response

​Suggested event order

Event fields

Example batch

Partial success response

Suggested event order