Events

Server-side events.

Generated

This page is generated from api/openapi/v1.yaml (OpenAPI 3.1.0, API version 1.0.0).

Send server-side events

POST/v1/properties/{pid}/events

Scope: events:write. Up to 500 events per call, using the same canonical model as the tag (page_view, purchase, add_to_cart, sign_up… or your own snake_case names). Events are forwarded to the collector and appear in reports within seconds. Each event needs a visitor_id or a user_id. Send an Idempotency-Key header to make retries safe: the first response is replayed for 24 hours. Use actor_type when your backend knows an agent acted (for example an order placed through an agent API).

Parameters

Name	In	Type	Required	Description
pid	path	string	yes	Property id.
Idempotency-Key	header	string		Makes retries safe. Same key + same body replays the first response for 24 hours; same key + different body answers 409.

Request body

Field	Type	Required	Description
events	array of object	yes

{
  "events": [
    {
      "name": "purchase",
      "user_id": "u_8f2c",
      "timestamp": "2026-10-29T14:03:00Z",
      "actor_type": "ai_agent",
      "actor_name": "chatgpt-agent",
      "ecommerce": {
        "transaction_id": "T-10293",
        "revenue": 129,
        "currency": "EUR",
        "items": [
          {
            "id": "SKU-4411",
            "name": "Trail runner 2",
            "price": 129,
            "quantity": 1
          }
        ]
      }
    }
  ]
}

Responses

Status	Description
202	Accepted and forwarded to the collector.
400	Invalid body or query (invalid_request), with errors[] for validation failures.
401	Missing, invalid, expired or revoked API key (unauthorized).
403	The key lacks the required scope (forbidden_scope).
404	Unknown endpoint, or a property / object that does not exist or is not accessible with this key (not_found).
409	Invalid body or query (invalid_request), with errors[] for validation failures.

Response fields

Field	Type	Required	Description
accepted	integer	yes	Number of events accepted.
batches	integer	yes	Number of wire batches sent to the collector.