# Business Agent Usage Insights
Retrieve billable messages, billable tokens, and charges for a Meta Business Agent account.
The Business Agent Usage Insights endpoint returns the number of billable messages, billable tokens, and [charges](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/non-template-messages#meta-business-agent-messages) for your Meta Business Agent account over a billing date range.
- Usage is returned as one entry per time bucket, at `HOUR`, `DAY`, or `MONTH` granularity. The minimum granularity is one hour.
- Split results by channel or sending entity with `dimensions` (`channel`, `sender_id`).
- Narrow results with the `channels` and `sender_ids` filters.
- Choose which metrics to return with `metric_types`; omit it to get all of them.
**What is a billable account ID**
The `entity_id` in the request below is your Meta Business Agent's billable account ID. Find it in [Billing Hub](https://business.facebook.com/latest/billing_hub/) under **Accounts** > **Meta Business Agent accounts**, where each account row displays its ID.
**Permissions**
This endpoint requires the `business_management` permission.
- If you're a direct developer using a system user token, grant your system user the `business_management` permission when you create its token.
- If you're a [Solution Provider](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/overview), call this endpoint with your client's [Business Integration System User (BISU) token](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens/#business-integration-system-user-access-tokens). To get the permission:
1. Get Advanced access for [`business_management`](https://developers.facebook.com/documentation/development/permissions#business_management) through App Review.
2. Add `business_management` to your Embedded Signup configuration.
3. Ask existing clients to complete Embedded Signup again. Their existing BISU tokens gain the permission, so you don't need to generate new tokens.
**Rate limit**
This endpoint allows 1,000 requests per hour for each app and `entity_id` pair. Once that is exhausted, further requests return `429` until the limit resets.
## Base URL
| URL | Description |
|-----|-------------|
| https://api.facebook.com/{entity_id}/business_agent_insights | |
## Authorization
This API requires:
any of the following
- Capability: bizai_wa_enterprise_api_3p_access
- Permission: business_management
## APIs
| Method | Endpoint |
|--------|----------|
| GET | [/](#get) |
<jumplink id="get"></jumplink>
## GET /
Get the business agent usage insights
Retrieve the agent usage over the requested billing date range.
### Header Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| X-API-Version | "3.0.0" | | |
### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| entity_id | integer [min: 1] | ✓ | The billable account ID of the business agent. Find it in [Billing Hub](https://business.facebook.com/latest/billing_hub/) under **Accounts** > **Meta Business Agent accounts**. |
### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| start | integer | ✓ | Start of the billing date range, as a Unix timestamp (seconds). Inclusive: only buckets that start at or after `start` are returned. Dates are evaluated in the billable account's timezone. For `MONTH`, this must be the first day of a month in the account's timezone. |
| end | integer | ✓ | End of the billing date range, as a Unix timestamp (seconds). Exclusive: only buckets that start before `end` are returned, so a `DAY` query ending at midnight on June 4 returns June 1 to June 3. Dates are evaluated in the billable account's timezone. For `MONTH`, this must fall on the last day of a month in the account's timezone. |
| granularity | string | ✓ | Size of each time bucket: `HOUR`, `DAY`, or `MONTH`. `MONTH` requires the range to span whole months in the billable account's timezone (start on the 1st, end on the last day of a month). |
| dimensions | array of string | | Axes to split usage by. Any of `channel`, `sender_id`. Omit to total the whole agent per bucket. Example: `channel`, `sender_id` |
| channels | array of string | | Restrict to these messaging surfaces: `whatsapp`. Example: `whatsapp` |
| sender_ids | array of string | | Restrict to these sending entities. Example: `109269195336416` |
| metric_types | array of string | | Which metrics to return. Any of `billable_messages`, `billable_tokens`, `cost`. Omit to return all of them. Example: `billable_tokens`, `cost` |
### Responses
**200**
The agent usage over the requested date range.
**Content Type**: `application/json`
**Schema**: [BusinessAgentInsightsResponse](#businessagentinsightsresponse)
**400**
Bad request
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**404**
Not found
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**401**
Unauthorized
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**403**
Forbidden
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**429**
Too many requests
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**500**
Server error
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
# Components
## Schemas
<jumplink id="businessagentinsightsresponse"></jumplink>
### BusinessAgentInsightsResponse
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| usage | array of [Usage](#object-usage-1) | ✓ | One entry per billing-time bucket, optionally broken down by channel and/or sending entity. An empty array means the agent had no usage in the requested range. |
<jumplink id="standarderror"></jumplink>
### StandardError
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| detail | string | ✓ | |
| status | integer | | |
| title | string | ✓ | |
| type | string | | |
## Inline Object Definitions
<jumplink id="object-usage-1"></jumplink>
### Usage
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| start | integer | ✓ | Start of the billing-time bucket, as a Unix timestamp (seconds). The bucket starts at an hour, day, or month boundary in the billable account's timezone. |
| end | integer | ✓ | End of the billing-time bucket, as a Unix timestamp (seconds). Exclusive: it equals the start of the next bucket. Buckets follow hour, day, and month boundaries in the billable account's timezone, so a day can be 23 or 25 hours long when daylight saving time changes. |
| channel | string | | Messaging surface the usage occurred on: `whatsapp`. Present only when `channel` is in `dimensions`. |
| sender_id | string | | The per-channel sending entity the usage is attributed to. Present only when `sender_id` is in `dimensions`. |
| billable_messages | integer | | Number of billable messages in this bucket. Present only when `billable_messages` is in `metric_types`. Included by default when `metric_types` is not passed. |
| billable_tokens | integer | | Number of billable tokens in this bucket. Present only when `billable_tokens` is in `metric_types`. Included by default when `metric_types` is not passed. |
| cost | number | | Charges for the usage in this bucket, in your Meta Business Agent account's currency. Omitted from the row entirely, not returned as null, when `cost` is excluded from `metric_types`. Included by default when `metric_types` is not passed. |
## Authentication
| Method | How to send it |
|--------|----------------|
| Authorization header | `Authorization: Bearer {access-token}` |
### Global Authentication Requirements
All endpoints require: `Authorization: Bearer {access-token}`