Query API - Grain Analytics

The Query API is the read path for your events. It returns the events that the Grain Tag and Analytics Web sent, as JSON, so that you can export them or show them in your own dashboard. The Query API needs the Builder plan or higher.

Base URL

https://queryapis.grainql.com/v1/api/query

Every path on this page and on the endpoint pages is relative to the base URL.

Authentication

Every request carries an API key in the X-API-Key header and a JSON content type.

X-API-Key: $GRAIN_API_KEY
Content-Type: application/json

Create the key in the dashboard:

Open https://grainql.com/dashboard/settings, then Authentication.
Click Generate New Secret.
Enter a name for the key.
Select the Query API permission.
Copy the secret. The dashboard shows it one time.

The Query API key is independent of the Analytics Web authStrategy. The key works when the SDK uses NONE, SERVER_SIDE, or JWT. Read Authentication.

Keep the API key in an environment variable on a server. Do not commit it to version control, and do not put it in browser code.

Endpoints

Method and path	Returns	Page
`POST /{tenantAlias}`	An array of events that match the filters, one page at a time.	Query events
`POST /count/{tenantAlias}`	The number of events that match the filters.	Count events
`GET /events/{tenantAlias}`	Every distinct event name of the tenant.	List event names

{tenantAlias} is the tenant alias that the dashboard shows. It is not the tenant UUID. A UUID in the path returns 404. Filters are the same on the query and count endpoints. Read Filters. The Query API does not write events. Send events with the Grain Tag or Analytics Web. Analytics Web has no Query API methods, so call these endpoints with an HTTP client.

Rate limits

The limit applies per API key. The plan sets the limit.

Plan	Requests per minute	Requests per day	Where
Free	Not available	Not available	every endpoint
Builder	2	20	every endpoint
Growth	10	200	every endpoint
Scale	100	2,000	every endpoint

Custom plans with higher limits exist.

Rate limit headers

A response near the limit carries three headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

Header	Value
`X-RateLimit-Limit`	The number of requests the window permits.
`X-RateLimit-Remaining`	The number of requests left in the window.
`X-RateLimit-Reset`	The Unix time at which the window resets.

A request over the limit gets 429 and a Retry-After header with a number of seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{ "error": "Rate limit exceeded. Upgrade for higher limits." }

If the API returns 429, wait Retry-After seconds, then retry the request one time.

Errors

Every error body is a JSON object with one error string.

Status	Value of `error`	Cause	What to do
`400`	`Invalid date format. Use YYYY-MM-DD format.`	A body field has the wrong shape.	Correct the field. Read the field table of the endpoint page.
`401`	`Missing X-API-Key header`	The request has no `X-API-Key` header.	Send the header.
`401`	`Invalid API key or insufficient permissions`	The key is unknown, or it has no Query API permission.	Create a key with the Query API permission and send that key.
`403`	`Query API requires Builder plan or higher. Upgrade at https://grainql.com/settings/billing`	The tenant is on the Free plan.	Change the plan of the tenant.
`404`	`Tenant not found`	The path holds a UUID or an unknown alias.	Use the tenant alias that the dashboard shows.
`429`	`Rate limit exceeded. Upgrade for higher limits.`	The key is over its rate limit.	Wait `Retry-After` seconds, then retry one time.

A filter with an unknown property path, an unknown operator, or a value of the wrong type also returns an error body. Read Filters.

Request format

The two POST endpoints take a JSON body. GET /events/{tenantAlias} takes no body.

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. `POST /{tenantAlias}` only. Holds `offset` and `size`.

{
  "event": "page_viewed",
  "after": "2024-01-01",
  "before": "2024-01-31",
  "filterSet": [
    { "property": "properties.device", "comparison": "EQUALS", "value": "mobile" }
  ],
  "pagination": { "offset": 0, "size": 100 }
}

Response format

POST /{tenantAlias} returns an array of event objects:

[
  {
    "eventName": "page_viewed",
    "userId": "user_123",
    "eventTs": "2024-01-15T10:30:00Z",
    "properties": {
      "page": "/home",
      "referrer": "https://google.com"
    },
    "eventDate": "2024-01-15",
    "insertId": "unique-event-id"
  }
]

POST /count/{tenantAlias} returns one object:

{ "count": 15247 }

GET /events/{tenantAlias} returns an array of strings:

["page_viewed", "purchase_completed"]

Limits

Limit	Value	Where
Page size	100 by default, 1000 at most	`pagination.size` in `POST /{tenantAlias}`
Page offset	0 by default	`pagination.offset` in `POST /{tenantAlias}`
Requests per minute and per day	Set by the plan. Read the rate limit table.	every endpoint

Base URL

​Authentication

​Endpoints

​Rate limits

​Rate limit headers

​Errors

​Request format

​Response format

​Limits

Authentication

Endpoints

Rate limits

Rate limit headers

Errors

Request format

Response format

Limits