Query events - Grain Analytics

POST /{tenantAlias} returns an array of event objects. The body selects the events, and pagination selects the page. The path is relative to the base URL https://queryapis.grainql.com/v1/api/query.

Request

POST /v1/api/query/{tenantAlias}
X-API-Key: $GRAIN_API_KEY
Content-Type: application/json

{tenantAlias} is the tenant alias that the dashboard shows, not the tenant UUID.

Field	Type	Rule
`event`	string	Optional. Only events with this `eventName` match.
`after`	string	Optional. Start date, `YYYY-MM-DD`.
`before`	string	Optional. End date, `YYYY-MM-DD`.
`filterSet`	array	Optional. Filter objects. Every filter must match.
`pagination`	object	Optional. Holds `offset` and `size`.

Each object in filterSet has three required fields:

Field	Type	Rule
`property`	string	Required. The property path, for example `properties.price` or `userId`.
`comparison`	string	Required. An operator such as `EQUALS` or `GREATER_THAN`.
`value`	any	Required. The value to compare with.

Read Filters for the operators and property paths. The pagination object has two optional fields:

Field	Type	Rule
`offset`	number	Optional. Events to skip, from 0. Default `0`.
`size`	number	Optional. Events per page. Default `100`. At most `1000`.

Example

curl -X POST https://queryapis.grainql.com/v1/api/query/your-tenant-id \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRAIN_API_KEY" \
  -d '{
    "event": "purchase_completed",
    "after": "2024-01-01",
    "before": "2024-01-31",
    "filterSet": [
      { "property": "properties.price", "comparison": "GREATER_THAN", "value": 100 }
    ],
    "pagination": { "offset": 0, "size": 100 }
  }'

const response = await fetch('https://queryapis.grainql.com/v1/api/query/your-tenant-id', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.GRAIN_API_KEY,
  },
  body: JSON.stringify({
    event: 'purchase_completed',
    after: '2024-01-01',
    before: '2024-01-31',
    filterSet: [
      { property: 'properties.price', comparison: 'GREATER_THAN', value: 100 },
    ],
    pagination: { offset: 0, size: 100 },
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Query failed: ${response.status} ${error}`);
}

const events = await response.json();

Response:

[
  {
    "eventName": "purchase_completed",
    "userId": "user_123",
    "eventTs": "2024-01-15T10:30:00Z",
    "properties": {
      "price": 249.99,
      "category": "electronics",
      "device": "desktop"
    },
    "eventDate": "2024-01-15",
    "insertId": "unique-event-id"
  }
]

Response fields

Field	Type	Notes
`eventName`	string	The name that `track` sent.
`userId`	string	The user who caused the event. Set by `identify` or `setUserId`.
`eventTs`	string	The time of the event, ISO 8601, UTC.
`properties`	object	The properties that `track` sent.
`eventDate`	string	The date part of `eventTs`, `YYYY-MM-DD`.
`insertId`	string	The unique identifier of the event.

Paging

Paging is by offset.

Send offset 0 and a size.
Add size to offset, then send the request again.
Repeat until a response holds fewer events than size.

curl -X POST https://queryapis.grainql.com/v1/api/query/your-tenant-id \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRAIN_API_KEY" \
  -d '{
    "event": "purchase_completed",
    "after": "2024-01-01",
    "before": "2024-01-31",
    "pagination": { "offset": 1000, "size": 1000 }
  }'

[]

An empty array means that the previous page was the last page.

Rules for the client

Send after and before on every request. A date range limits the data that the server scans.
Set event when you want one event name. It is faster than a filter on eventName.
Do not page through events to count them. Read Count events.
When the order matters, sort by eventTs on the client.
If the API returns 429, wait Retry-After seconds, then retry one time. Read Query API for the rate limits and the error table.

Limits

Limit	Value	Where
Page size	100 by default, 1000 at most	`pagination.size`
Page offset	0 by default	`pagination.offset`
Requests per minute and per day	Set by the plan	every request

​Request

​Example

​Response fields

​Paging

​Rules for the client

​Limits