Cano Analytics Events API — Track and Query Events

The Events API is the core of Cano Analytics — it lets you ingest events from your servers and query the full event stream by user, event name, or time window. All requests require a valid API key sent as a Bearer token in the Authorization header.

POST /v1/events — Track an Event

Send a single event to Cano Analytics. This endpoint requires the write scope.

Request headers

Header	Value
`Authorization`	`Bearer <YOUR_API_KEY>`
`Content-Type`	`application/json`

Body parameters

string

required

The name of the event in snake_case format (e.g. page_viewed, order_completed).

string

The unique identifier for the authenticated user. Either user_id or anonymous_id must be present.

string

A unique identifier for an anonymous user (e.g. a cookie or device ID). Required when user_id is not provided.

object

A free-form key-value object containing additional metadata about the event (e.g. { "plan": "pro", "amount": 49.00 }).

string

An ISO 8601 timestamp indicating when the event occurred. Defaults to the server’s current time if omitted.

Request example

POST /v1/events

{
  "event": "order_completed",
  "user_id": "usr_4f8a1c",
  "properties": {
    "order_id": "ord_9921",
    "amount": 149.00,
    "currency": "USD",
    "plan": "pro"
  },
  "timestamp": "2024-06-15T14:32:00Z"
}

Response — 200 OK

string

The unique ID assigned to this event by Cano Analytics.

string

Always "received" for a successful ingest.

string

ISO 8601 timestamp recording when Cano Analytics received the event.

200 OK

{
  "id": "evt_7kXm29pQrL",
  "status": "received",
  "received_at": "2024-06-15T14:32:01.043Z"
}

Error responses

Status	Meaning
`400 Bad Request`	The payload is malformed or missing required fields. Check that `event` is present and either `user_id` or `anonymous_id` is provided.
`401 Unauthorized`	The API key is missing, expired, or lacks the `write` scope.

POST /v1/events/batch — Batch Track Events

Send up to 1,000 events in a single HTTP request to reduce network overhead. The batch endpoint accepts the same event shape as the single-event endpoint, wrapped in an events array.

Body parameters

array

required

An array of event objects. Each object follows the same schema as the single POST /v1/events body. Maximum 1,000 items per request.

Request example

POST /v1/events/batch

{
  "events": [
    {
      "event": "page_viewed",
      "user_id": "usr_4f8a1c",
      "properties": { "path": "/pricing" },
      "timestamp": "2024-06-15T14:30:00Z"
    },
    {
      "event": "cta_clicked",
      "user_id": "usr_4f8a1c",
      "properties": { "button": "Start free trial" },
      "timestamp": "2024-06-15T14:30:45Z"
    },
    {
      "event": "signup_completed",
      "user_id": "usr_4f8a1c",
      "properties": { "plan": "pro", "referral": "google" },
      "timestamp": "2024-06-15T14:31:10Z"
    }
  ]
}

Response — 200 OK

200 OK

{
  "received": 3,
  "failed": 0
}

If some events in the batch are invalid, Cano Analytics still ingests the valid ones and reports the count of failures. Inspect the optional errors array in the response for details on which items failed.

GET /v1/events — List Events

Query your event stream with optional filters. This endpoint requires the read scope and returns results in reverse-chronological order with cursor-based pagination.

Query parameters

string

Filter results to a specific event name (e.g. event=order_completed).

string

Filter results to events belonging to a specific user.

string

ISO 8601 timestamp. Return only events that occurred at or after this time.

string

ISO 8601 timestamp. Return only events that occurred at or before this time.

integer

Number of events to return. Defaults to 100. Maximum is 1000.

string

Opaque pagination cursor returned in the previous response’s next_cursor field. Pass this to retrieve the next page.

Request example

cURL

curl -G https://api.canoanalytics.io/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "event=order_completed" \
  --data-urlencode "user_id=usr_4f8a1c" \
  --data-urlencode "from=2024-06-01T00:00:00Z" \
  --data-urlencode "limit=2"

Response fields

array

An array of event objects matching your query filters, each containing id, event, user_id, properties, and timestamp.

string

An opaque string to pass as cursor in your next request to retrieve the following page. null when no more pages exist.

boolean

true if additional pages of results are available beyond the current response.

200 OK

{
  "data": [
    {
      "id": "evt_7kXm29pQrL",
      "event": "order_completed",
      "user_id": "usr_4f8a1c",
      "properties": {
        "order_id": "ord_9921",
        "amount": 149.00,
        "currency": "USD"
      },
      "timestamp": "2024-06-15T14:32:00Z"
    },
    {
      "id": "evt_3hWn01mBkA",
      "event": "order_completed",
      "user_id": "usr_4f8a1c",
      "properties": {
        "order_id": "ord_8810",
        "amount": 49.00,
        "currency": "USD"
      },
      "timestamp": "2024-06-03T09:17:22Z"
    }
  ],
  "next_cursor": "cur_eyJvZmZzZXQiOjJ9",
  "has_more": true
}

Overview

Endpoints

SDKs

Cano Analytics Events API — Track and Query Events

POST /v1/events — Track an Event

Request headers

Body parameters

Request example

Response — 200 OK

Error responses

POST /v1/events/batch — Batch Track Events

Body parameters

Request example

Response — 200 OK

GET /v1/events — List Events

Query parameters

Request example

Response fields

​POST /v1/events — Track an Event

​Request headers

​Body parameters

​Request example

​Response — 200 OK

​Error responses

​POST /v1/events/batch — Batch Track Events

​Body parameters

​Request example

​Response — 200 OK

​GET /v1/events — List Events

​Query parameters

​Request example

​Response fields

POST /v1/events — Track an Event

Request headers

Body parameters

Request example

Response — 200 OK

Error responses

POST /v1/events/batch — Batch Track Events

Body parameters

Request example

Response — 200 OK

GET /v1/events — List Events

Query parameters

Request example

Response fields