Events

Track events in a batch

POST/v1/events/batch

Requires an API key with the events:write scope. About keys and scopes

Each entry takes its own idempotencyKey, so retrying the whole batch never acts twice on an entry that already went through. About idempotency

Up to 100 events in one request, each stored exactly as POST /v1/events/track would, in order, under its own idempotencyKey in place of the header. One event refused does not stop the rest: its entry carries the error a single track would have answered, and a key already used answers the stored event with replayed: true. Retry a failed batch whole; the keys stop anything being stored twice. Counts against the rate limit as one request per event.

Request body

eventsobject[]required

at least 1 item · at most 100 items

2 child attributes

idempotencyKeystringrequired

As the Idempotency-Key header of a single track: one per event you mean.

8–255 characters

eventobjectrequired

One of 3 shapes

By contact id

5 child attributes

contactIdstringrequired

Kirora's id for the contact.

uuid

eventNamestringrequired

Case-sensitive, up to 128 characters; contact.* is reserved.

1–128 characters

propertiesobjectoptional

Free-form details of the event; at most 16 KB, keys up to 64 characters.

default {}

occurredAtstringoptional

When it happened; defaults to now. At most 24 hours ahead.

date-time

contextEventContextInputoptional

Where and on what it happened, beside the properties.

9 child attributes

sessionIdstringoptional

The visit, from the SDK.

up to 128 characters

localestringoptional

As BCP 47, en-GB.

up to 35 characters

timezonestringoptional

As IANA, Europe/Berlin.

up to 64 characters

pageobjectoptional

Web: the page, without its query string or fragment.

campaignobjectoptional

Web: the utm_* parameters of the page.

deviceobjectoptional

libraryobjectoptional

ipstringoptional

up to 64 characters

userAgentstringoptional

up to 1024 characters

By external id

5 child attributes

externalIdstringrequired

Your own id for the contact, as set with identify.

1–255 characters

eventNamestringrequired

Case-sensitive, up to 128 characters; contact.* is reserved.

1–128 characters

propertiesobjectoptional

Free-form details of the event; at most 16 KB, keys up to 64 characters.

default {}

occurredAtstringoptional

When it happened; defaults to now. At most 24 hours ahead.

date-time

contextEventContextInputoptional

Where and on what it happened, beside the properties.

9 child attributes

sessionIdstringoptional

The visit, from the SDK.

up to 128 characters

localestringoptional

As BCP 47, en-GB.

up to 35 characters

timezonestringoptional

As IANA, Europe/Berlin.

up to 64 characters

pageobjectoptional

Web: the page, without its query string or fragment.

campaignobjectoptional

Web: the utm_* parameters of the page.

deviceobjectoptional

libraryobjectoptional

ipstringoptional

up to 64 characters

userAgentstringoptional

up to 1024 characters

By email

5 child attributes

emailstringrequired

The contact's email address, matched trimmed and without case.

eventNamestringrequired

Case-sensitive, up to 128 characters; contact.* is reserved.

1–128 characters

propertiesobjectoptional

Free-form details of the event; at most 16 KB, keys up to 64 characters.

default {}

occurredAtstringoptional

When it happened; defaults to now. At most 24 hours ahead.

date-time

contextEventContextInputoptional

Where and on what it happened, beside the properties.

9 child attributes

sessionIdstringoptional

The visit, from the SDK.

up to 128 characters

localestringoptional

As BCP 47, en-GB.

up to 35 characters

timezonestringoptional

As IANA, Europe/Berlin.

up to 64 characters

pageobjectoptional

Web: the page, without its query string or fragment.

campaignobjectoptional

Web: the utm_* parameters of the page.

deviceobjectoptional

libraryobjectoptional

ipstringoptional

up to 64 characters

userAgentstringoptional

up to 1024 characters

Returns

Returns 200 OK with a TrackEventsResult in data. Otherwise returns an error; Errors lists every code and which to retry.

resultsobject[]required

One of 2 shapes

Event recorded

3 child attributes

idempotencyKeystringrequired

replayedbooleanrequired

True when the key was used before and the stored event is returned.

eventTrackedEventrequired

2 child attributes

idstringrequired: uuid
occurredAtstringrequired: date-time

Event refused

2 child attributes

idempotencyKeystringrequired

errorobjectrequired

4 child attributes

codestringrequired: one of BAD_REQUEST, ALREADY_EXISTS, CONFLICT, IN_USE, FORBIDDEN, INTERNAL_ERROR, NOT_FOUND, RATE_LIMITED, REVISION_CONFLICT, SERVICE_UNAVAILABLE, UNAUTHORIZED, VALIDATION_ERROR, API_KEY_IP_NOT_ALLOWED, AGENT_CONFIRMATION_REQUIRED, EMBED_ORIGIN_NOT_ALLOWED, WORKSPACE_SUSPENDED, WORKSPACE_DELETION_PENDING, CONTACT_SEND_IN_PROGRESS, EXPORT_UNAVAILABLE, NOTHING_TO_EXPORT, EVENT_NAME_LIMIT_REACHED, PLAN_LIMIT_REACHED, PLAN_FEATURE_UNAVAILABLE, CAMPAIGN_AUDIENCE_CONFLICT, EMPTY_AUDIENCE, INVALID_CAMPAIGN_CONTENT, DRAFT_INCOMPLETE, INVALID_SCHEDULE, UNSUPPORTED_CHANNEL, POSTAL_ADDRESS_MISSING, CONSENT_MISSING, SUPPRESSED, SIGNUP_BLOCKED, INVALID_SENDER_ADDRESS, SENDING_DOMAIN_DMARC_MISSING, SENDING_DOMAIN_IDENTITY_CONFLICT, SENDING_DOMAIN_UNVERIFIED, IDEMPOTENCY_KEY_REUSED, CONTENT_NOT_RETAINED, RECIPIENT_EMAIL_MISSING, TEMPLATE_NOT_PUBLISHED, TEMPLATE_ENVELOPE_INCOMPLETE, PUSH_APP_NOT_READY, PUSH_DESTINATION_MISSING
messagestringrequired
detailsobjectoptional
requestIdstringoptional

curl -X POST https://api.kirora.io/v1/events/batch \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "idempotencyKey": "order-1001-completed",
        "event": {
          "externalId": "customer-4821",
          "eventName": "Order Completed",
          "properties": {
            "order_id": "1001",
            "total": 45.5,
            "currency": "USD"
          },
          "occurredAt": "2026-10-01T09:30:00Z"
        }
      },
      {
        "idempotencyKey": "order-1002-completed",
        "event": {
          "externalId": "customer-5307",
          "eventName": "Order Completed",
          "properties": {
            "order_id": "1002",
            "total": 18.5,
            "currency": "USD"
          },
          "occurredAt": "2026-10-01T09:30:00Z"
        }
      }
    ]
  }'

const response = await fetch('https://api.kirora.io/v1/events/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "events": [
      {
        "idempotencyKey": "order-1001-completed",
        "event": {
          "externalId": "customer-4821",
          "eventName": "Order Completed",
          "properties": {
            "order_id": "1001",
            "total": 45.5,
            "currency": "USD"
          },
          "occurredAt": "2026-10-01T09:30:00Z"
        }
      },
      {
        "idempotencyKey": "order-1002-completed",
        "event": {
          "externalId": "customer-5307",
          "eventName": "Order Completed",
          "properties": {
            "order_id": "1002",
            "total": 18.5,
            "currency": "USD"
          },
          "occurredAt": "2026-10-01T09:30:00Z"
        }
      }
    ]
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/events/batch",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "events": [
            {
                "idempotencyKey": "order-1001-completed",
                "event": {
                    "externalId": "customer-4821",
                    "eventName": "Order Completed",
                    "properties": {
                        "order_id": "1001",
                        "total": 45.5,
                        "currency": "USD",
                    },
                    "occurredAt": "2026-10-01T09:30:00Z",
                },
            },
            {
                "idempotencyKey": "order-1002-completed",
                "event": {
                    "externalId": "customer-5307",
                    "eventName": "Order Completed",
                    "properties": {
                        "order_id": "1002",
                        "total": 18.5,
                        "currency": "USD",
                    },
                    "occurredAt": "2026-10-01T09:30:00Z",
                },
            },
        ],
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "events": [
	    {
	      "idempotencyKey": "order-1001-completed",
	      "event": {
	        "externalId": "customer-4821",
	        "eventName": "Order Completed",
	        "properties": {
	          "order_id": "1001",
	          "total": 45.5,
	          "currency": "USD"
	        },
	        "occurredAt": "2026-10-01T09:30:00Z"
	      }
	    },
	    {
	      "idempotencyKey": "order-1002-completed",
	      "event": {
	        "externalId": "customer-5307",
	        "eventName": "Order Completed",
	        "properties": {
	          "order_id": "1002",
	          "total": 18.5,
	          "currency": "USD"
	        },
	        "occurredAt": "2026-10-01T09:30:00Z"
	      }
	    }
	  ]
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/events/batch", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 200

{
  "data": {
    "results": [
      {
        "idempotencyKey": "order-1001-completed",
        "replayed": false,
        "event": {
          "id": "0192f3c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
          "occurredAt": "2026-10-01T09:30:00.000Z"
        }
      },
      {
        "idempotencyKey": "order-1002-completed",
        "replayed": false,
        "event": {
          "id": "0192f3c0-2b3c-7d4e-9f50-6b7c8d9e0f1a",
          "occurredAt": "2026-10-01T09:30:00.000Z"
        }
      }
    ]
  }
}

curl -X POST https://api.kirora.io/v1/events/batch \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "idempotencyKey": "order-1003-completed",
        "event": {
          "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
          "eventName": "Order Completed",
          "occurredAt": "2026-10-01T09:30:00Z"
        }
      },
      {
        "idempotencyKey": "order-1004-completed",
        "event": {
          "email": "nobody@example.com",
          "eventName": "Order Completed",
          "occurredAt": "2026-10-01T09:30:00Z"
        }
      }
    ]
  }'

const response = await fetch('https://api.kirora.io/v1/events/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "events": [
      {
        "idempotencyKey": "order-1003-completed",
        "event": {
          "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
          "eventName": "Order Completed",
          "occurredAt": "2026-10-01T09:30:00Z"
        }
      },
      {
        "idempotencyKey": "order-1004-completed",
        "event": {
          "email": "nobody@example.com",
          "eventName": "Order Completed",
          "occurredAt": "2026-10-01T09:30:00Z"
        }
      }
    ]
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/events/batch",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "events": [
            {
                "idempotencyKey": "order-1003-completed",
                "event": {
                    "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
                    "eventName": "Order Completed",
                    "occurredAt": "2026-10-01T09:30:00Z",
                },
            },
            {
                "idempotencyKey": "order-1004-completed",
                "event": {
                    "email": "nobody@example.com",
                    "eventName": "Order Completed",
                    "occurredAt": "2026-10-01T09:30:00Z",
                },
            },
        ],
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "events": [
	    {
	      "idempotencyKey": "order-1003-completed",
	      "event": {
	        "contactId": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
	        "eventName": "Order Completed",
	        "occurredAt": "2026-10-01T09:30:00Z"
	      }
	    },
	    {
	      "idempotencyKey": "order-1004-completed",
	      "event": {
	        "email": "nobody@example.com",
	        "eventName": "Order Completed",
	        "occurredAt": "2026-10-01T09:30:00Z"
	      }
	    }
	  ]
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/events/batch", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 200

{
  "data": {
    "results": [
      {
        "idempotencyKey": "order-1003-completed",
        "replayed": false,
        "event": {
          "id": "0192f3c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
          "occurredAt": "2026-10-01T09:30:00.000Z"
        }
      },
      {
        "idempotencyKey": "order-1004-completed",
        "error": {
          "code": "NOT_FOUND",
          "message": "Contact not found"
        }
      }
    ]
  }
}