# 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** &gt; **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}`