Query API - GrainQL

The Query API is the read path for your events. It returns the events that the GrainQL 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 Starter plan or higher. Read Plans and limits.

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 Settings, then API keys, at https://grainql.com/dashboard/settings/api-keys.
Click Create key.
Enter a name for the key.
Under Access, select Query API.
Copy the key. 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 GrainQL 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 workspace. Every API key of the workspace counts against the same limit. The limit is the same on every plan.

Limit	Value	Where
Requests per minute	120, in a sliding window of 60 seconds	every endpoint
Requests per day	No daily limit	every endpoint

Rate limit headers

Every response carries three headers:

X-RateLimit-Limit: 120
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: 12
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Maximum 120 requests per minute allowed.",
  "retryAfter": 12
}

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

Errors

Every error body is a JSON object with an error string. A 429 body also has message and retryAfter.

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 Starter plan or higher. Upgrade at https://grainql.com/settings/billing`	The workspace has no paid plan.	Choose a plan in Settings, then Plan and billing.
`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`	The workspace sent more than 120 requests in 60 seconds.	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	120 per workspace. 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