> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/mba/api-ref/insights/get-the-business-agent-usage-insights.md).

# Get the business agent usage insights

Retrieve the billable messages, billable tokens, and charges for a Meta Business Agent account over the requested billing date range, as one entry per HOUR, DAY, or MONTH bucket. Split results by channel or sending entity with dimensions, narrow them with the channels and sender\_ids filters, and choose which metrics to return with metric\_types. Reported tokens are billed tokens, the same figure used to calculate your invoice, which may be fewer than the total tokens the agent used to produce a response.

```json
{"openapi":"3.1.0","info":{"title":"Business Agent API","version":"1.51.5"},"tags":[{"name":"Insights","description":"Endpoints for retrieving the agent's usage insights"}],"servers":[{"description":"Production server","url":"https://waba-v2.360dialog.io"}],"security":[{"D360-API-KEY":[]}],"components":{"securitySchemes":{"D360-API-KEY":{"description":"API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.","in":"header","name":"D360-API-KEY","type":"apiKey"}},"schemas":{"insights.BusinessAgentInsightsResponse":{"description":"The agent usage over the requested date range","properties":{"usage":{"description":"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","items":{"$ref":"#/components/schemas/insights.BusinessAgentUsage"},"type":"array","uniqueItems":false}},"required":["usage"],"type":"object"},"insights.BusinessAgentUsage":{"description":"Billable messages, billable tokens, and charges for a single billing-time bucket","properties":{"billable_messages":{"description":"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","type":"integer"},"billable_tokens":{"description":"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","type":"integer"},"channel":{"description":"Messaging surface the usage occurred on: whatsapp. Present only when channel is in dimensions","enum":["whatsapp"],"type":"string"},"cost":{"description":"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","type":"number"},"end":{"description":"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","type":"integer"},"sender_id":{"description":"The per-channel sending entity the usage is attributed to. Present only when sender_id is in dimensions","type":"string"},"start":{"description":"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","type":"integer"}},"required":["end","start"],"type":"object"},"insights.StandardError":{"description":"Standard error response for Meta Business Agent endpoints","properties":{"detail":{"description":"Human-readable explanation of the error","type":"string"},"status":{"description":"HTTP status code","type":"integer"},"title":{"description":"Short, human-readable summary of the problem","type":"string"},"type":{"description":"A URI reference identifying the problem type","type":"string"}},"type":"object"}}},"paths":{"/insights/usage/{entity_id}":{"get":{"description":"Retrieve the billable messages, billable tokens, and charges for a Meta Business Agent account over the requested billing date range, as one entry per HOUR, DAY, or MONTH bucket. Split results by channel or sending entity with dimensions, narrow them with the channels and sender_ids filters, and choose which metrics to return with metric_types. Reported tokens are billed tokens, the same figure used to calculate your invoice, which may be fewer than the total tokens the agent used to produce a response.","operationId":"get-business-agent-usage-insights","parameters":[{"description":"Meta Business Agent API version","in":"header","name":"X-API-Version","schema":{"enum":["3.0.0"],"type":"string"}},{"description":"The billable account ID of the business agent. Find it in Billing Hub under Accounts > Meta Business Agent accounts.","in":"path","name":"entity_id","required":true,"schema":{"minimum":1,"type":"integer"}},{"description":"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.","in":"query","name":"start","required":true,"schema":{"type":"integer"}},{"description":"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.","in":"query","name":"end","required":true,"schema":{"type":"integer"}},{"description":"Size of each time bucket. 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).","in":"query","name":"granularity","required":true,"schema":{"enum":["HOUR","DAY","MONTH"],"type":"string"}},{"description":"Axes to split usage by. Omit to total the whole agent per bucket.","in":"query","name":"dimensions","schema":{"items":{"enum":["channel","sender_id"],"type":"string"},"type":"array"},"style":"form","explode":false},{"description":"Restrict to these messaging surfaces.","in":"query","name":"channels","schema":{"items":{"enum":["whatsapp"],"type":"string"},"type":"array"},"style":"form","explode":false},{"description":"Restrict to these sending entities.","in":"query","name":"sender_ids","schema":{"items":{"type":"string"},"type":"array"},"style":"form","explode":false},{"description":"Which metrics to return. Omit to return all of them.","in":"query","name":"metric_types","schema":{"items":{"enum":["billable_messages","billable_tokens","cost"],"type":"string"},"type":"array"},"style":"form","explode":false}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.BusinessAgentInsightsResponse"}}},"description":"The agent usage over the requested date range"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/insights.StandardError"}}},"description":"Server error"}},"summary":"Get the business agent usage insights","tags":["Insights"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.360dialog.com/docs/mba/api-ref/insights/get-the-business-agent-usage-insights.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.