> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grainql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Count events

> POST /count/{tenantAlias} returns the number of events that match your filters.

`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

```http theme={null}
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](/api-reference/query-api/filters) for the operators and property paths.

An empty body `{}` counts every event of the tenant.

## Example

<CodeGroup>
  ```bash curl theme={null}
  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" }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

Response:

```json theme={null}
{ "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

1. Send `after` and `before` on every request. A date range limits the data that the server
   scans.
2. 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.
3. Cache a count that a dashboard shows often. Every request counts against the rate limit.
4. If the API returns `429`, wait `Retry-After` seconds, then retry one time. Read
   [Query API](/api-reference/query-api/overview) for the rate limits and the error table.

## Limits

| Limit | Value | Where |
| - | - | - |
| Requests per minute and per day | Set by the plan | every request |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.