Count events - Grain Analytics

POST /count/{tenantAlias} returns one number: the count of events that match the body. It takes the same filters as POST /{tenantAlias} and no pagination. The path is relative to the base URL https://queryapis.grainql.com/v1/api/query.

Request

POST /v1/api/query/count/{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` count.
`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.

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. An empty body {} counts every event of the tenant.

Example

curl -X POST https://queryapis.grainql.com/v1/api/query/count/your-tenant-id \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRAIN_API_KEY" \
  -d '{
    "event": "page_viewed",
    "after": "2024-01-01",
    "before": "2024-01-31",
    "filterSet": [
      { "property": "properties.page", "comparison": "EQUALS", "value": "/signup" }
    ]
  }'

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

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

const { count } = await response.json();

Response:

{ "count": 12543 }

Response fields

Field	Type	Notes
`count`	number	The number of events that match the body. `0` when nothing matches.

When to use count

Task	Endpoint
A total for a dashboard widget	Count
A rate, for example errors divided by all events	Count, one request per number
Whether an event exists at all	Count
A threshold check, for example an alert on an error rate	Count
The event data itself	Query
A user journey, in order	Query
An export	Query
The properties of one event	Query

A count is one small response. A query for the same events returns every event object, one page at a time, and each page is one request against the rate limit.

Rules for the client

Send after and before on every request. A date range limits the data that the server scans.
To compute a rate, send one count per number, then divide on the client. For example, count error_occurred and count every event, then divide.
Cache a count that a dashboard shows often. Every request counts against the rate limit.
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
Requests per minute and per day	Set by the plan	every request

​Request

​Example

​Response fields

​When to use count

​Rules for the client

​Limits