---
title: "Estimate marketing reach for a maximum price"
canonical: "https://bird.com/docs/api/reference/get-whatsapp-business-account-reach-estimate"
---

# Estimate marketing reach for a maximum price

`GET /v1/whatsapp/business-accounts/{business_account_ref}/reach-estimate`

Returns Meta's estimate of how many marketing deliveries, and at what cost,
each candidate maximum price would have won over `window`. Use it to choose
a template language's `optimization_spec.bid_amount`.

Every amount is per 1,000 deliveries, in the smallest unit of
`currency_code`. Estimates come from Meta's recent auctions and are not a
guarantee. Bird asks Meta on every request and stores nothing.

Every country must support a maximum price. One that does not fails the
whole request with E15090. WhatsApp does not say which country, so estimate
the countries one at a time to find it.

## Servers

- `https://{region}.platform.bird.com`: Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
  - `region`: `us1`, `eu1`. Default: `us1`. The region your organization's data is hosted in.
- `https://platform.bird.com`: Region-independent endpoint for authentication and account administration.
- `http://localhost:8080`: Local development.

## Authentication

Use one authentication option:

- `BearerAuth`: HTTP bearer authentication. Pass the API key as a bearer token in the `Authorization` header. Workspace
keys use `bk_{region}_*`; organization master keys use `bm_{region}_*`.
The prefix identifies the region and selects the
API endpoint. Official Bird SDKs and the CLI derive the region from the key.

- `CookieAuth`: Send `bird_session` in cookie. Session cookie set after signing in to the Bird dashboard. The cookie
value is an opaque session token; no session data is stored in the cookie
itself.

## Code samples

**CLI**

```sh
bird whatsapp business-accounts reach-estimate <business-account-ref>
```

Examples: [CLI](/docs/api/reference/get-whatsapp-business-account-reach-estimate.cli.md) · [cURL](/docs/api/reference/get-whatsapp-business-account-reach-estimate.curl.md)

## Example response `200`

```json
{
  "currency_code": "EUR",
  "estimates": [
    {
      "bid_amount": 2590,
      "users": 1000,
      "deliveries_lower_bound": 67,
      "deliveries_upper_bound": 267,
      "cost_lower_bound": 1940.6530830145,
      "cost_upper_bound": 2590
    }
  ]
}
```

## Path parameters

- `business_account_ref` (string, required): WhatsApp Business Account ID (`waa_` prefix) or the WhatsApp Business Account ID Meta reports in `waba`. A value that parses as a valid ID resolves by ID; any other value resolves as Meta's ID.

## Query parameters

- `countries` (array, required): The recipients' countries, as ISO 3166-1 alpha-2 codes. Repeat the parameter for several.
- `window` (string, optional)

  The days of recent auctions the estimate is based on, ending now. Omit it to use the last 7 days.

  Possible values: `1d`, `7d`, `14d`, `28d`

## Header parameters

- `X-Workspace-Id` (string, optional): Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.
- `X-Organization-Id` (string, optional): Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

## Response body

- `currency_code` (string, required): The currency of every amount in `estimates`.
- `estimates` (array of object, required): One estimate per candidate bid, in ascending bid order.
- `estimates.bid_amount` (integer, required): The candidate bid, per 1,000 deliveries in the smallest currency unit. It is the unit `optimization_spec.bid_amount` takes.
- `estimates.users` (integer, required): The audience size the estimate is for.
- `estimates.deliveries_lower_bound` (integer, required)
- `estimates.deliveries_upper_bound` (integer, required)
- `estimates.cost_lower_bound` (number, required): The lower cost estimate, per 1,000 deliveries in the smallest currency unit.
- `estimates.cost_upper_bound` (number, required): The upper cost estimate, per 1,000 deliveries in the smallest currency unit.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)