---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/whatsapp/api/message-cost-estimate-resource#article
headline: Message Cost Estimate resource
description: Estimate WhatsApp reach and cost with Meta's reach-estimation tool through the Twilio Message Cost Estimate API
url: https://www.twilio.com/docs/whatsapp/api/message-cost-estimate-resource
inLanguage: en
dateModified: 2026-11-17T10:37:33.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Message Cost Estimate resource

The Message Cost Estimate API returns Meta reach estimates for a specified destination country. Use these estimates to understand how expected deliveries and costs vary at different `bid_amount` values before you launch a WhatsApp campaign that uses Max Price.

Estimates are based on historical data and are informational only. Meta doesn't publish the underlying algorithm, and the actual delivery volume and cost can differ for each send because of audience size, message volume, and recipient behavior.

## Prerequisites

* Onboard your account to Max Price and accept the Terms of Service for the Marketing Messages API.
* Your WhatsApp Business Account (WABA) currency must be supported for Max Pricing.

## Get a cost estimate

Request an estimate for a country and a look-back window. The estimate is independent of a specific template, so you don't need to request one estimate per template.

### Query parameters

| Query parameter  | Required | Description                                                                                                                                  |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `country`        | Yes      | The destination country for the estimate, for example `BR`.                                                                                  |
| `lookbackWindow` | Yes      | The historical window Meta uses to compute the estimate. Valid values: `L1D`, `L7D`, `L14D`, or `L28D`. The example that follows uses `L7D`. |

You can't pass `bid_amount` in this request. The response includes estimates for several bid amounts so you can choose one and set it when you create your MARKETING content template.

```bash title="Request"
curl -G "https://messaging.twilio.com/v3/MessageCostEstimate" \
  -u "$TWILIO_API_KEY:$TWILIO_API_SECRET" \
  -H "Content-Type: application/json" \
  --data-urlencode "country=BR" \
  --data-urlencode "lookbackWindow=L7D"
```

```bash title="Response"
{
  "country": "BR",
  "currency": "USD",
  "disclaimer": "Estimates are based on historical data and are informational only; actual delivery and cost may vary.",
  "estimates": [
    {
      "bidAmount": 2500,
      "estimatedCost": { "lower": 0, "upper": 0 },
      "estimatedDeliveries": { "lower": 0, "upper": 0 },
      "targetedUsers": 1000
    },
    {
      "bidAmount": 3125,
      "estimatedCost": { "lower": 2356.8175590276, "upper": 3113.5824409724 },
      "estimatedDeliveries": { "lower": 125, "upper": 325 },
      "targetedUsers": 1000
    },
    {
      "bidAmount": 12500,
      "estimatedCost": { "lower": 3403.3, "upper": 4481.3 },
      "estimatedDeliveries": { "lower": 669, "upper": 867 },
      "targetedUsers": 1000
    }
  ],
  "lookbackWindow": "L7D"
}
```

### Response properties

| Property                          | Description                                                                                                                                |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `country`                         | The country for which the estimate is calculated.                                                                                          |
| `currency`                        | The currency of the monetary amounts in the response.                                                                                      |
| `lookbackWindow`                  | The look-back window used to generate the estimate.                                                                                        |
| `disclaimer`                      | Reminder that the data is informational only.                                                                                              |
| `estimates`                       | A list of estimates, one for each bid amount.                                                                                              |
| `estimates[].bidAmount`           | The bid amount (in the smallest unit of the WABA currency) that the estimate applies to.                                                   |
| `estimates[].estimatedCost`       | The estimated cost as `lower` and `upper` bounds.                                                                                          |
| `estimates[].estimatedDeliveries` | The estimated number of deliveries as `lower` and `upper` bounds.                                                                          |
| `estimates[].targetedUsers`       | The number of targeted users the estimate is based on. This figure is a sampling size, not a limit on the number of messages you can send. |

### Use the estimate to choose a bid amount

`bid_amount` is the maximum price per 1,000 message deliveries, expressed in the smallest unit of your WABA currency (for example, cents, centavos, or pence). The factor of 1,000 is part of Meta's pricing formula and isn't a limit on how many messages you can send.

* If `bid_amount` matches your current fixed rate, your costs stay the same or decrease.
* If `bid_amount` is higher than the fixed rate, the average cost per message can increase, but you might reach a larger audience and see fewer failed deliveries.
* If you don't set `bid_amount`, Twilio applies standard fixed rate cards and Max Price doesn't apply.

## Rate limits

The Message Cost Estimate API has a dedicated rate limit to protect other WhatsApp operations on your account, such as template creation and phone number onboarding.

| Limit type | Value                           |
| ---------- | ------------------------------- |
| Requests   | 20 per hour, per Twilio account |
| Burst      | Up to 20 requests               |

If you exceed the limit, Twilio returns HTTP status `429 Too Many Requests`. Wait before you retry, and use exponential backoff in automated clients.

Meta's estimates typically change only a few times per day, so polling is unnecessary. Request an estimate while planning your campaign, cache the result, and reuse it as needed.

This limit applies only to the Message Cost Estimate API. It is separate from Twilio's general REST API concurrency limits and from message-sending throughput limits.
