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

# Usage

> What you sent, spent and called through the API, by hour, day, week or month.

`GET /v1/usage/report` gives the same numbers as Developer → Usage in the app: the messages you sent with your API keys, what they cost, and your API calls. Any key can read it.

```bash cURL theme={null}
curl "https://api.getreply.in/v1/usage/report?from=2026-11-07&to=2026-11-13&group_by=day" \
  -H "Authorization: Bearer gr_live_…"
```

```javascript Node.js theme={null}
const res = await fetch("https://api.getreply.in/v1/usage/report?from=2026-11-07&to=2026-11-13&group_by=day", {
  method: "GET",
  headers: {
    "Authorization": "Bearer gr_live_…",
  },
});
console.log(await res.json());
```

```php PHP theme={null}
<?php
$ch = curl_init("https://api.getreply.in/v1/usage/report?from=2026-11-07&to=2026-11-13&group_by=day");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer gr_live_…",
  ],
]);
echo curl_exec($ch);
```

```python Python theme={null}
import requests

res = requests.get(
    "https://api.getreply.in/v1/usage/report?from=2026-11-07&to=2026-11-13&group_by=day",
    headers={
        "Authorization": "Bearer gr_live_…",
    },
)
print(res.json())
```

## Parameters

* `from`: First day, like 2026-11-07 (India time). Default: 6 days before to.
* `to`: Last day, like 2026-11-13 (India time). Default: today.
* `group_by`: hour, day, week or month. Default: day. hour works for one day only. Weeks start on Monday.
* `key`: An API key's id. Repeat it to pick more than one. Leave it out for all keys.

A wrong value answers `validation_error` with the `field` and a `reason`. A key that is not yours: "No key with this id."

## What is counted

* **Messages**: messages sent with an API key that reached WhatsApp or failed. `read`, `delivered` (delivered, not read), `sent` (accepted by WhatsApp, no delivery report yet) and `failed`.
* **Spent**: what each message was charged, in rupees, by the category it was charged as. A failed message adds nothing.
* Messages and spend include campaigns made with the key.
* **Requests** and **errors**: your API calls, and those answered with an error.

## Answer

```json theme={null}
{
  "currency": "INR",
  "from": "2026-11-07",
  "to": "2026-11-13",
  "group_by": "day",
  "keys": null,
  "totals": { "spent": "2166.46", "messages": 4948, "delivered": 1290, "read": 3120, "sent": 408, "failed": 130, "requests": 6146, "errors": 101 },
  "spent_by_category": { "marketing": "1890.12", "utility": "251.30", "authentication": "25.04" },
  "buckets": [
    {
      "start": "2026-11-07T00:00:00.000+05:30",
      "end": "2026-11-08T00:00:00.000+05:30",
      "spent": "301.55",
      "spent_by_category": { "marketing": "262.10", "utility": "35.80", "authentication": "3.65" },
      "messages": 702,
      "messages_by_category": { "marketing": 287, "utility": 247, "authentication": 25, "service": 143 },
      "read": 455,
      "delivered": 190,
      "sent": 39,
      "failed": 18,
      "requests": 871,
      "errors": 14
    }
  ],
  "by_key": [
    { "key_id": "KEY_ID", "name": "Website", "deleted": false, "messages": 3010, "delivered": 2790, "spent": "1612.40", "requests": 3830, "errors": 62, "last_used_at": "2026-11-13T08:21:04.000+05:30" }
  ],
  "errors": [
    { "code": "invalid_number", "message": "Not a valid number.", "count": 41, "last_seen_at": "2026-11-13T07:52:10.000+05:30" }
  ],
  "by_country": [
    { "country": "IN", "messages": 4810, "delivered": 4290, "spent": "2010.15" }
  ],
  "by_endpoint": [
    { "method": "POST", "path": "/v1/messages/template", "requests": 3420, "errors": 58, "average_ms": 412 }
  ]
}
```

Money is text in rupees with 2 decimals; times are India time (`+05:30`). In `by_key` and `by_country`, `delivered` counts messages delivered or read.


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