Querying the Snowplow Hosted Micro /events Endpoint

Overview

This article explains how to query the Snowplow Micro /events endpoint when running Micro through the Snowplow Console. It covers exchanging your API key for a short lived access token, calling the endpoint with that token, and shaping the request body to filter, sort, and paginate the events Micro has cached.

The endpoint is available at https://<uuid>.apps.snowplowanalytics.com/micro/events, where <uuid> identifies your development environment Micro instance.

Before You Start

You will need four values to authenticate and address the correct Micro instance. Gather these from the Console before you begin.

Micro UUID → found in Console under Pipelines → Development environment. The UUID is embedded in the Collector URL.
API_KEY_ID and API_KEY_SECRET → created in Console under Settings → Manage Organization → API keys.
ORG_ID → found in Console under Settings → Manage Organization. The Organization UUID is shown at the top of that page.

Step 1: Exchange Your API Key for an Access Token

The /events endpoint accepts a Bearer token, so you first exchange your API key for a short lived JWT using the v3 credentials endpoint. Two headers are required.

curl \
  --header 'X-API-Key-ID: <API_KEY_ID>' \
  --header 'X-API-Key: <API_KEY_SECRET>' \
  'https://console.snowplowanalytics.com/api/msc/v1/organizations/<ORG_ID>/credentials/v3/token'

The response contains the token you will use in the next step.

{ "accessToken": "<JWT>" }

The JWT is short lived, so you will request a fresh one for each session.

Step 2: Call the /events Endpoint

Pass the JWT as a Bearer token in the Authorization header and send a POST request with a JSON body to the Micro base URL.

curl -X POST \
  -H 'Authorization: Bearer <JWT>' \
  -H 'Content-Type: application/json' \
  -d '<body>' \
  'https://<uuid>.apps.snowplowanalytics.com/micro/events'

Request Body

The request body controls which events are returned, how they are filtered and sorted, and how results are paginated.

{
  "validEvents": true,
  "filters": [
    { "column": "<field_name>", "value": "<match_value>" }
  ],
  "timeRange": {
    "start": "2026-05-21T00:00:00Z",
    "end": "2026-05-21T23:59:59Z"
  },
  "sorting": {
    "column": "<field_name>",
    "desc": true
  },
  "page": 1,
  "pageSize": 50
}

Body fields

Field	Type	Purpose
`validEvents`	boolean or null	`true` returns good events only, `false` returns bad events only, omitting it or setting null returns both
`filters`	array of {column, value}	Case insensitive substring filters. Stack multiple entries for AND logic. Use `[]` when no filtering is needed
`timeRange.start`	ISO 8601 string	Earliest event timestamp, inclusive
`timeRange.end`	ISO 8601 string	Latest event timestamp, inclusive
`sorting.column`	string	Column to sort by
`sorting.desc`	boolean	`true` sorts descending
`page`	integer	Page number, 1 based
`pageSize`	integer	Events per page

The column values used in filters and sorting correspond to Snowplow enriched event field names, for example event_name, app_id, user_id, collector_tstamp, and contexts_*.

Response Shape

The response returns the matching events along with pagination totals.

{
  "events": [...],
  "totalPages": 4,
  "totalItems": 192
}

Filter Examples

Good events only, paginated

-d '{"validEvents": true, "filters": [], "page": 1, "pageSize": 25}'

Bad events only

-d '{"validEvents": false, "filters": [], "page": 1, "pageSize": 25}'

Filter by a specific column value within a time window

-d '{
  "validEvents": true,
  "filters": [{"column": "event_name", "value": "page_view"}],
  "timeRange": {"start": "2026-05-21T09:00:00Z", "end": "2026-05-21T17:00:00Z"},
  "sorting": {"column": "collector_tstamp", "desc": true},
  "page": 1,
  "pageSize": 100
}'