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

# Reporting

> Track API usage and performance.

export const Throttling = () => {
  return <Warning>
      This endpoint is rate limited; if you receive a <code>429</code> response, pause for the
      backoff time required by the <code>Retry-After</code> header before making another request.
    </Warning>;
};

export const Reference = ({endpoint}) => {
  return <Info>
      See also the <Link href={`reference/${endpoint}`}>API reference</Link> for more detail.
    </Info>;
};

export const apiEndpoint = 'render.joinmassive.com';

export const companyName = 'Massive';

<Reference endpoint="usage" />

## Service usage

**{companyName}'s** reporting service buckets and updates consumption, success, and latency metrics
at intervals of **1 hour**. The service has a RESTful interface that accepts `GET` requests at
**https\://‍{apiEndpoint}/usage**.

### Authentication

You can access the service by including your secret API token in an `Authorization` header:

```http theme={null}
Authorization: Bearer [API token here]
```

Here's an example request that uses the [common Curl command](https://curl.se/):

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/usage'\
'?from=2025-12-24'\
'&to=2025-12-25'
```

<Throttling />

### Report parameters

You should specify an ISO date or time range to generate a report:

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/usage'\
'?from=2025-12-24T18:00:00-06:00'\
'&to=2025-12-25T9:00:00-06:00'
```

The API will return a JSON array:

```json theme={null}
[{
  "email": "user@example.com",
  "from": "2025-12-25T00:00:00+00:00",
  "to": "2025-12-25T15:00:00+00:00",
  "service": "browser",
  "result": "success",
  "calls": 17208,
  "meanSecs": 6.78
}, {
  "email": "user@example.com",
  "from": "2025-12-25T01:00:00+00:00",
  "to": "2025-12-25T15:00:00+00:00",
  "service": "browser",
  "result": "failure",
  "calls": 18,
  "meanSecs": 60.22
}]
```

Your report can optionally be filtered by one or more services:

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/usage'\
'?from=2025-12-24'\
'&to=2025-12-25'\
'&service=search'
```

<Accordion icon="terminal" title="View multiple-service example">
  ```shell theme={null}
  curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
  'https://render.joinmassive.com/usage'\
  '?from=2025-12-24'\
  '&to=2025-12-25'\
  '&service=search'\
  '&service=ai'
  ```
</Accordion>

You can also disaggregate the metrics:

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/usage'\
'?from=2025-12-24'\
'&to=2025-12-25'\
'&by=hour'
```

These are the request keys and values:

| Key       | Required | Value                                                                                                                                                                                                             |
| :-------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`    | ✅        | The [ISO datetime](https://www.w3.org/TR/NOTE-datetime) to select data starting from, inclusively                                                                                                                 |
| `to`      | ✅        | The [ISO datetime](https://www.w3.org/TR/NOTE-datetime) to select data up to, inclusively                                                                                                                         |
| `email`   | ⬜        | **\[Whitelabelers only]** The (case-insensitive) email address of the user to select data for; multiple email addresses can be provided by repeating the key; data for all email addresses is included by default |
| `service` | ⬜        | The service to select data for, `search`, `ai`, or `browser`; multiple services can be provided by repeating the key; data for all services is included by default                                                |
| `by`      | ⬜        | The time unit to group the data by, `hour`, `day` (planned), or `total`; `total` is the default unit                                                                                                              |

These are the response keys and values:

| Key        | Value                                                           |
| :--------- | :-------------------------------------------------------------- |
| `email`    | The email address of the user whose data is selected            |
| `from`     | The ISO datetime of the first datapoint                         |
| `to`       | The ISO datetime of the last datapoint                          |
| `service`  | The service included in the data, `search`, `ai`, or `browser`  |
| `result`   | The type of result included in the data, `success` or `failure` |
| `calls`    | The number of API calls of the service and result type          |
| `meanSecs` | The average number of elapsed seconds of the API calls          |