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.

get

Authorizations

D360-API-KEYstringRequired

API Key for Messaging API authentication. Send your API key in the D360-API-KEY header.

Path parameters

entity_idinteger · min: 1Required

The billable account ID of the business agent. Find it in Billing Hub under Accounts > Meta Business Agent accounts.

Query parameters

startintegerRequired

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.

endintegerRequired

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.

granularitystring · enumRequired

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).

Possible values:

sender_idsstring[]Optional

Restrict to these sending entities.

Header parameters

X-API-Versionstring · enumOptional

Meta Business Agent API version

Possible values:

Responses

200

The agent usage over the requested date range

application/json

The agent usage over the requested date range

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Server error

application/json

get/insights/usage/{entity_id}

GET /insights/usage/{entity_id}?start=1&end=1&granularity=HOUR HTTP/1.1
Host: waba-v2.360dialog.io
D360-API-KEY: YOUR_API_KEY
Accept: */*

{
  "usage": [
    {
      "billable_messages": 120,
      "billable_tokens": 48000,
      "channel": "whatsapp",
      "cost": 1.25,
      "end": 1780387200,
      "sender_id": "109269195336416",
      "start": 1780300800
    }
  ]
}