curl --request POST \
  --url https://api.upstackdata.com/tr/api/events \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-pixel-id: <api-key>' \
  --data '
{
  "events": [
    {
      "name": "purchase",
      "eventId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "userProperties": {
        "emails": [
          "jane@example.com"
        ],
        "userIds": [
          "cust_889"
        ]
      },
      "ipAddress": "203.0.113.5",
      "page": {
        "url": "https://shop.com/checkout"
      },
      "click": {
        "fbc": "fb.1.abc",
        "gclid": "xyz"
      },
      "eventProperties": {
        "orderId": "10421",
        "value": 99.9,
        "currency": "USD",
        "items": [
          {
            "id": "SKU1",
            "name": "Tee",
            "price": 49.95,
            "quantity": 2
          }
        ]
      }
    }
  ]
}
'

{
  "requestId": "18d90656-34fd-4b87-b1e2-9607943d97a9",
  "eventsIngested": 3
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

EVENTS

Send server-side events

Send a batch of tracking events from your server. Each event is turned into Upstack’s canonical event and processed exactly like a pixel event — identity resolution, enrichment, analytics, and real-time forwarding to your destinations.

You always send an array of events (send one event as an array of one). Each event needs a name. An eventId is optional but strongly recommended — it makes the event idempotent (safe retries and de-duplication); everything else is optional.

Deduplication. eventId is your idempotency key. If the same eventId is received again for a pixel within the dedup window, the duplicate is skipped during processing — so retries and webhook loops are safe. Use the same eventId you send from your browser Pixel for the same event so they de-duplicate across sources (e.g. Facebook).

Limits. Up to 100 events per request; request body up to 128 KB. Within event data: strings up to 1024 chars, arrays up to 100 items, objects up to 50 keys (key names up to 64 chars), nested up to 4 levels deep.

Required scope: events:write.

POST

api

events

curl --request POST \
  --url https://api.upstackdata.com/tr/api/events \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-pixel-id: <api-key>' \
  --data '
{
  "events": [
    {
      "name": "purchase",
      "eventId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "userProperties": {
        "emails": [
          "jane@example.com"
        ],
        "userIds": [
          "cust_889"
        ]
      },
      "ipAddress": "203.0.113.5",
      "page": {
        "url": "https://shop.com/checkout"
      },
      "click": {
        "fbc": "fb.1.abc",
        "gclid": "xyz"
      },
      "eventProperties": {
        "orderId": "10421",
        "value": 99.9,
        "currency": "USD",
        "items": [
          {
            "id": "SKU1",
            "name": "Tee",
            "price": 49.95,
            "quantity": 2
          }
        ]
      }
    }
  ]
}
'

{
  "requestId": "18d90656-34fd-4b87-b1e2-9607943d97a9",
  "eventsIngested": 3
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

{
  "requestId": "<string>",
  "message": "<string>",
  "error": {
    "message": "<string>",
    "details": [
      {
        "message": "<string>",
        "index": 123,
        "field": "<string>"
      }
    ]
  }
}

Authorizations

x-api-key

string

header

required

Your Upstack API key. Starts with upstack_.

x-pixel-id

string

header

required

The pixel id the request targets.

Body

application/json

events

object[]

required

The events to ingest. At least 1, at most 100 per request.

Required array length: 1 - 100 elements

Show child attributes

Response

Events accepted for processing. eventsIngested is the number queued.

requestId

string

required

Unique id for this request (also the x-request-id header).

eventsIngested

integer

required

Number of events accepted and queued for processing.

Delete a COG line

⌘I