List eventsMenu

List events

GET/v1/events

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

Works with integration, agent and partner keys.

Every event the workspace tracked, accepted or rejected, newest first: did an integration's event arrive, and if not, why? Accepted events are ordered and filtered by when they happened, rejected ones by when they arrived; the log reaches back meta.retention. A rejected event is a tracked event the API refused (validation, an unknown contact, the name limit, a deleted name), kept as sent with the error it answered; a batch refused whole is listed event by event. A request refused before its body was read (credentials, rate limit, plan, size, broken JSON) is not kept. query matches an event name exactly, or a contact's id, email address or external id (accepted events only: a rejected one has no contact); property values are not searched. Complete, not sampled. For a member, a property whose key is a masked attribute is left out, as on contact reads.

Query parameters

limitintegeroptional

How many items a page holds: 1 to 100, 20 by default.

min > 0 · max 100 · default 20

cursorstringoptional

Where the page starts: the previous page's meta.pagination.nextCursor. Omit it for the first page, and send the same filters with it.

1–2,048 characters

namestringoptional

Only events of this name.

1–128 characters

statusstringoptional

Only accepted events, or only rejected ones (refused, kept with the error).

one of accepted, rejected

sourcestringoptional

Only events that came in this way. Nothing indexes it, so a page polling for new events also sets occurredAfter.

one of api, web, system, stripe, zapier, make, n8n, segment

querystringoptional

An event name, exactly as tracked, or a contact's id, email address or external id. Property values are not searched.

1–320 characters

occurredAfterstringoptional

Only events that happened at or after this time (inclusive), a rejected one by when it arrived; the log reaches back meta.retention at most.

date-time

occurredBeforestringoptional

Only events that happened before this time (exclusive).

date-time

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Returns

Returns 200 OK with a list of Event objects in data, and the next page's cursor in meta (see pagination). Otherwise returns an error; Errors lists every code and which to retry.

One of 2 shapes:

Accepted

10 child attributes

idstringrequired

uuid

sourcestringrequired

The path it came in on, set by Kirora: api (an API key), web (the Kirora web SDK), system (recorded by Kirora) or the integration that sent it. A key made for an app labels its events with that app, whoever uses the key.

one of api, web, system, stripe, zapier, make, n8n, segment

receivedAtstringrequired

When Kirora received it.

date-time

status"accepted"required

namestringrequired

contactobjectrequired

3 child attributes

idstringrequired: uuid
externalIdstring | nullrequired
emailstring | nullrequired

propertiesmap<string, any>required

As tracked, less any key masked from this viewer.

contextobject | nullrequired

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 as visited: query strings kept, fragments removed. A longer value is cut, not refused: url, search and referrer at 8192 characters, path at 2048, title at 256.

5 child attributes

urlstringoptional: The canonical URL if the page has one, with the page's query string added unless it has its own; else the page's address.
pathstringoptional
searchstringoptional: The visited address's query string, ?plan=pro; empty or absent when it has none.
titlestringoptional
referrerstringoptional

campaignobjectoptional

Web: the utm_* parameters of the page, each cut to 256 characters.

5 child attributes

sourcestringoptional
mediumstringoptional
namestringoptional
termstringoptional
contentstringoptional

deviceobjectoptional

1 child attribute

idstringoptional

A random id the SDK keeps on the device; never a hardware id.

up to 128 characters

libraryobjectoptional

2 child attributes

namestringoptional: up to 64 characters
versionstringoptional: up to 64 characters

ipstringoptional

up to 64 characters

userAgentstringoptional

up to 1,024 characters

occurredAtstringrequired

When it happened.

date-time

expiresAtstringrequired

When retention deletes it: when it happened plus the days the plan kept events when it was stored. Fixed: a plan change moves only later events.

date-time

Rejected

8 child attributes

idstringrequired

uuid

sourcestringrequired

one of api, web, system, stripe, zapier, make, n8n, segment

receivedAtstringrequired

When Kirora received it.

date-time

status"rejected"required

namestring | nullrequired

Null when the request had no valid name.

occurredAtstring | nullrequired

When it happened; null when the request gave no valid time.

date-time

payloadobjectrequired

The event as sent, less masked property keys; null when it was over 32 KB.

errorobjectrequired

The error the API answered.

5 child attributes

codestringrequired

one of BAD_REQUEST, ALREADY_EXISTS, CONFLICT, IN_USE, FORBIDDEN, SCOPE_MISSING, AGENT_KEY_REFUSED, INTERNAL_ERROR, NOT_FOUND, METHOD_NOT_ALLOWED, PAYLOAD_TOO_LARGE, UNSUPPORTED_MEDIA_TYPE, RATE_LIMITED, REVISION_CONFLICT, SERVICE_UNAVAILABLE, UNAUTHORIZED, VALIDATION_ERROR, API_KEY_IP_NOT_ALLOWED, AGENT_CONFIRMATION_REQUIRED, EMBED_BUILDER_UNAVAILABLE, 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, SENDING_REVIEW_REQUIRED, PLAN_FEATURE_UNAVAILABLE, CAMPAIGN_AUDIENCE_CONFLICT, EMPTY_AUDIENCE, DRAFT_INCOMPLETE, INVALID_SCHEDULE, UNSUPPORTED_CHANNEL, POSTAL_ADDRESS_MISSING, CONSENT_MISSING, SUPPRESSED, TOPIC_UNSUBSCRIBED, SIGNUP_BLOCKED, INVALID_SENDER_ADDRESS, SENDING_DOMAIN_DMARC_MISSING, SENDING_DOMAIN_IDENTITY_CONFLICT, TEST_SEND_OUTCOME_UNKNOWN, TEST_SEND_ROUTE_NOT_READY, TEST_SEND_UNAVAILABLE, SENDING_DOMAIN_UNVERIFIED, IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_KEY_IN_USE, IDEMPOTENCY_KEY_OUTCOME_UNKNOWN, CONTENT_NOT_RETAINED, RECIPIENT_EMAIL_MISSING, RECIPIENT_EMAIL_UNSUPPORTED, TEMPLATE_NOT_PUBLISHED, TEMPLATE_ENVELOPE_INCOMPLETE, PUSH_APP_NOT_READY, PUSH_DESTINATION_MISSING, FORM_CLOSED

messagestringrequired

errorsFieldError[]optional

Each field the request got wrong: on VALIDATION_ERROR and DRAFT_INCOMPLETE.

6 child attributes

instringoptional

The part of the request the field is in, when known.

one of body, query, params, headers

fieldstringrequired

Dotted path to the field (blocks.0.text); empty for the whole part.

codestringoptional

The rule that failed (too_big, invalid_type, custom, …).

messagestringrequired

Plain words, meant to be shown beside the field.

minimumnumberoptional

The bound a too_small rule set.

maximumnumberoptional

The bound a too_big rule set.

detailsobjectoptional

What else the error carries, by code: see that code's description.

requestIdstringoptional

curl https://api.kirora.io/v1/events \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/events', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data, meta } = await response.json();
// meta.pagination.nextCursor is the next page's `cursor`, and null on the last page.

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/events",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
body = response.json()
data = body["data"]
next_cursor = body["meta"]["pagination"]["nextCursor"]
# next_cursor is the next page's `cursor`, and None on the last page.

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/events", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
		Meta struct {
			Pagination struct {
				NextCursor *string `json:"nextCursor"`
			} `json:"pagination"`
		} `json:"meta"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
	// out.Meta.Pagination.NextCursor is the next page's `cursor`, and nil on the last page.
}

using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.kirora.io/v1/events");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");
var nextCursor = document.RootElement.GetProperty("meta").GetProperty("pagination").GetProperty("nextCursor");
// nextCursor is the next page's `cursor`, and null on the last page.

Response · 200

{
  "data": [
    {
      "id": "0192f3c0-3c4d-7e5f-8a61-7c8d9e0f1a2b",
      "status": "rejected",
      "name": "Order Completed",
      "source": "api",
      "occurredAt": null,
      "receivedAt": "2026-10-01T09:31:12.480Z",
      "payload": {
        "email": "not-an-email",
        "name": "Order Completed"
      },
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "Some request values are invalid. Check the field errors.",
        "errors": [
          {
            "in": "body",
            "field": "email",
            "message": "Enter an email address, like [email protected]."
          }
        ]
      }
    },
    {
      "id": "0192f3c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "status": "accepted",
      "name": "Order Completed",
      "contact": {
        "id": "0192f3a1-7c2e-7d4b-9a10-3e5f6a7b8c9d",
        "externalId": "customer-4821",
        "email": "[email protected]"
      },
      "properties": {
        "order_id": "1001",
        "total": 46.5,
        "currency": "USD"
      },
      "context": {
        "library": {
          "name": "kirora-web",
          "version": "1.4.0"
        },
        "page": {
          "url": "https://shop.example/checkout"
        }
      },
      "source": "web",
      "occurredAt": "2026-10-01T09:30:00.000Z",
      "receivedAt": "2026-10-01T09:30:01.204Z",
      "expiresAt": "2027-10-01T09:30:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 20,
      "nextCursor": null
    },
    "retention": {
      "value": 30,
      "unit": "days"
    }
  }
}