Get Template Metrics

What it does

Returns Meta’s template analytics for up to 10 templates of a single application: an overall summary, a per-template summary, and a daily series.

Gap-filled buckets — days Meta returns no data for are emitted as zero points, so the series is always continuous across the requested range.
Pending days — zero points beyond Meta’s dataAvailableUntil watermark are flagged isPending: true, telling you the day is not yet aggregated rather than genuinely empty.
Derived rates — deliveredRate, readRate, clickRate, and costPerDelivered are computed for you and rounded to 4 decimals.

This endpoint is per-application and per-template. For organization-wide message volume, use Get Messages instead.

Endpoint

GET /api/v1/wa/{app_id}/templates/metrics

There are no body parameters.

Headers

string

required

Secret key in Bearer sk_... format. See Secret Key authentication.

Path parameters

string

required

Application ID. Must belong to the organization (otherwise 404).

Query parameters

string[]

required

Repeatable: ?templateId=a&templateId=b. Between 1 and 10 IDs per request. Blank values are discarded and duplicates are collapsed before the request reaches Meta; more than 10 distinct IDs returns 422.

string

default:"30 days before today 00:00:00 (UTC)"

ISO-8601 datetime. Start of the range.

string

default:"today 23:59:59 (UTC)"

ISO-8601 datetime. End of the range. Must be greater than startDate, and the total span cannot exceed 90 days.

string

default:"DAILY"

Bucket size of the series. DAILY is the only value Meta exposes for template analytics, so this is effectively fixed.

string[]

default:"core set"

Repeatable. Omit for the full core set (SENT, DELIVERED, READ, CLICKED, COST). Conversion metrics can be requested explicitly. See Template Metrics Metric Type.

string

Restricts the result to one messaging product: CLOUD_API or MARKETING_MESSAGES_LITE_API. Omit for all products.

boolean

default:"false"

When true, Meta buckets the days in the WABA’s own timezone instead of UTC. The applied choice is echoed back as usesWabaTimezone.

Limits: at most 10 templateId values and at most a 90-day range per request. Split larger reports into several calls.

Response

The envelope is { "data": {...}, "isSuccess": true }, where data carries the range metadata, an overall summary, and one entry per requested template.

boolean

true when the request completed successfully.

object

Show data

string

The granularity Meta applied (echoed from Meta, falling back to the requested value).

string

The messaging product the numbers belong to. Dropped when Meta does not report one.

string

ISO-8601 start of the requested range.

string

ISO-8601 end of the requested range.

string

ISO-8601 watermark: the latest moment Meta has aggregated data for. Buckets after it are returned with isPending: true. Dropped when Meta returned no data at all.

boolean

Whether the buckets follow the WABA timezone (useWabaTimezone) instead of UTC.

object

Totals across every requested template. Same shape as a template summary (see below).

object[]

One entry per requested templateId, in the order you sent them. A template with no data is still returned, with a zeroed summary and a fully gap-filled series.

Show template

string

The template’s Meta ID.

object

Totals for this template across the range.

Show summary

integer

Messages sent.

integer

Messages delivered.

integer

Messages read.

integer

Button clicks. Counts url_button and quick_reply_button only — unique_url_button is excluded so clicks are not double-counted.

number

delivered / sent, rounded to 4 decimals. 0 when sent is 0.

number

read / delivered, rounded to 4 decimals.

number

clicked / delivered, rounded to 4 decimals.

number

Total spend for the range, rounded to 6 decimals.

number

amountSpent / delivered, rounded to 4 decimals.

object[]

Clicks grouped by type + buttonContent. Each item has type (see Template Metrics Click Type), buttonContent (the button label or URL; dropped when Meta does not report one), and count.

object[]

Cost lines with type (see Template Metrics Cost Type) and value. Empty when the range contains no cost data.

object[]

One point per day in the range, including days Meta returned nothing for.

Show series item

string

ISO-8601 start of the bucket.

string

ISO-8601 end of the bucket.

integer

Messages sent in this bucket.

integer

Messages delivered in this bucket.

integer

Messages read in this bucket.

integer

Button clicks in this bucket (same counting rule as the summary).

number

delivered / sent for this bucket.

number

read / delivered for this bucket.

number

clicked / delivered for this bucket.

number

Spend in this bucket.

boolean

true for a zero-filled bucket that Meta has not aggregated yet (it falls after dataAvailableUntil). false for a real data point or for a day that is genuinely empty.

object

Any extra metric Meta returns for this bucket that is not part of the core set — for example the conversion metrics you requested via metricType. Dropped when there are none.

object[]

Per-bucket click breakdown, same shape as in the summary.

object[]

Per-bucket cost breakdown, same shape as in the summary.

Invariants: Σ series[].sent == summary.sent for each template (the same holds for delivered, read, clicked, and amountSpent), and the top-level summary is the sum of every template summary. Rates are always recomputed from the totals, never averaged from the buckets.

Examples

Demo 1 — single template (defaults: last 30 days, daily)

GET /api/v1/wa/app_7poyXj8GXuv76e/templates/metrics?templateId=842802041844912
Authorization: Bearer sk_...

{
  "data": {
    "granularity": "DAILY",
    "productType": "CLOUD_API",
    "periodStart": "2026-07-14T00:00:00+00:00",
    "periodEnd": "2026-08-13T23:59:59+00:00",
    "dataAvailableUntil": "2026-08-13T00:00:00+00:00",
    "usesWabaTimezone": false,
    "summary": {
      "sent": 1200, "delivered": 1140, "read": 860, "clicked": 210,
      "deliveredRate": 0.95, "readRate": 0.7544, "clickRate": 0.1842,
      "amountSpent": 18.42, "costPerDelivered": 0.0162,
      "clicksBreakdown": [ { "type": "url_button", "buttonContent": "Track Order", "count": 210 } ],
      "costBreakdown": [
        { "type": "amount_spent", "value": 18.42 },
        { "type": "cost_per_delivered", "value": 0.0162 }
      ]
    },
    "templates": [
      {
        "templateId": "842802041844912",
        "summary": {
          "sent": 1200, "delivered": 1140, "read": 860, "clicked": 210,
          "deliveredRate": 0.95, "readRate": 0.7544, "clickRate": 0.1842,
          "amountSpent": 18.42, "costPerDelivered": 0.0162,
          "clicksBreakdown": [ { "type": "url_button", "buttonContent": "Track Order", "count": 210 } ],
          "costBreakdown": [
            { "type": "amount_spent", "value": 18.42 },
            { "type": "cost_per_delivered", "value": 0.0162 }
          ]
        },
        "series": [
          {
            "periodStart": "2026-08-12T00:00:00+00:00",
            "periodEnd": "2026-08-13T00:00:00+00:00",
            "sent": 400, "delivered": 380, "read": 290, "clicked": 70,
            "deliveredRate": 0.95, "readRate": 0.7632, "clickRate": 0.1842,
            "amountSpent": 6.14, "isPending": false,
            "clicksBreakdown": [ { "type": "url_button", "buttonContent": "Track Order", "count": 70 } ],
            "costBreakdown": [ { "type": "amount_spent", "value": 6.14 } ]
          }
        ]
      }
    ]
  },
  "isSuccess": true
}

Demo 2 — multiple templates (repeatable templateId)

GET /api/v1/wa/app_7poyXj8GXuv76e/templates/metrics?templateId=842802041844912&templateId=1560534655590931&startDate=2026-08-01T00:00:00&endDate=2026-08-08T00:00:00
Authorization: Bearer sk_...

The top-level summary aggregates both templates, while templates[] keeps them separate and in the order you sent them:

{
  "data": {
    "granularity": "DAILY",
    "periodStart": "2026-08-01T00:00:00+00:00",
    "periodEnd": "2026-08-08T00:00:00+00:00",
    "dataAvailableUntil": "2026-08-08T00:00:00+00:00",
    "usesWabaTimezone": false,
    "summary": { "sent": 1700, "delivered": 1605, "read": 1180, "clicked": 265, "deliveredRate": 0.9441, "readRate": 0.7352, "clickRate": 0.1651, "amountSpent": 26.1, "costPerDelivered": 0.0163, "clicksBreakdown": [], "costBreakdown": [ { "type": "amount_spent", "value": 26.1 }, { "type": "cost_per_delivered", "value": 0.0163 } ] },
    "templates": [
      { "templateId": "842802041844912", "summary": { "sent": 1200, "delivered": 1140, "read": 860, "clicked": 210, "deliveredRate": 0.95, "readRate": 0.7544, "clickRate": 0.1842, "amountSpent": 18.42, "costPerDelivered": 0.0162, "clicksBreakdown": [], "costBreakdown": [] }, "series": [] },
      { "templateId": "1560534655590931", "summary": { "sent": 500, "delivered": 465, "read": 320, "clicked": 55, "deliveredRate": 0.93, "readRate": 0.6882, "clickRate": 0.1183, "amountSpent": 7.68, "costPerDelivered": 0.0165, "clicksBreakdown": [], "costBreakdown": [] }, "series": [] }
    ]
  },
  "isSuccess": true
}

Demo 3 — pending days (today is not aggregated yet)

GET /api/v1/wa/app_7poyXj8GXuv76e/templates/metrics?templateId=842802041844912&startDate=2026-08-11T00:00:00&endDate=2026-08-13T23:59:59
Authorization: Bearer sk_...

Meta has aggregated up to 2026-08-12T00:00:00, so the following bucket is emitted as a zero point flagged isPending: true — the day is not empty, it is simply not ready.

{
  "data": {
    "granularity": "DAILY",
    "periodStart": "2026-08-11T00:00:00+00:00",
    "periodEnd": "2026-08-13T23:59:59+00:00",
    "dataAvailableUntil": "2026-08-12T00:00:00+00:00",
    "usesWabaTimezone": false,
    "summary": { "sent": 400, "delivered": 380, "read": 290, "clicked": 70, "deliveredRate": 0.95, "readRate": 0.7632, "clickRate": 0.1842, "amountSpent": 6.14, "costPerDelivered": 0.0162, "clicksBreakdown": [], "costBreakdown": [ { "type": "amount_spent", "value": 6.14 }, { "type": "cost_per_delivered", "value": 0.0162 } ] },
    "templates": [
      {
        "templateId": "842802041844912",
        "summary": { "sent": 400, "delivered": 380, "read": 290, "clicked": 70, "deliveredRate": 0.95, "readRate": 0.7632, "clickRate": 0.1842, "amountSpent": 6.14, "costPerDelivered": 0.0162, "clicksBreakdown": [], "costBreakdown": [] },
        "series": [
          { "periodStart": "2026-08-11T00:00:00+00:00", "periodEnd": "2026-08-12T00:00:00+00:00", "sent": 400, "delivered": 380, "read": 290, "clicked": 70, "deliveredRate": 0.95, "readRate": 0.7632, "clickRate": 0.1842, "amountSpent": 6.14, "isPending": false, "clicksBreakdown": [], "costBreakdown": [] },
          { "periodStart": "2026-08-12T00:00:00+00:00", "periodEnd": "2026-08-13T00:00:00+00:00", "sent": 0, "delivered": 0, "read": 0, "clicked": 0, "deliveredRate": 0, "readRate": 0, "clickRate": 0, "amountSpent": 0, "isPending": true, "clicksBreakdown": [], "costBreakdown": [] }
        ]
      }
    ]
  },
  "isSuccess": true
}

Demo 4 — conversion metrics (metricType) → additionalMetrics

GET /api/v1/wa/app_7poyXj8GXuv76e/templates/metrics?templateId=1560534655590931&metricType=SENT&metricType=DELIVERED&metricType=WEBSITE_PURCHASES&productType=MARKETING_MESSAGES_LITE_API
Authorization: Bearer sk_...

Metrics outside the core set are surfaced per bucket under additionalMetrics:

{
  "data": {
    "granularity": "DAILY",
    "productType": "MARKETING_MESSAGES_LITE_API",
    "periodStart": "2026-07-14T00:00:00+00:00",
    "periodEnd": "2026-08-13T23:59:59+00:00",
    "usesWabaTimezone": false,
    "summary": { "sent": 500, "delivered": 465, "read": 0, "clicked": 0, "deliveredRate": 0.93, "readRate": 0, "clickRate": 0, "amountSpent": 0, "costPerDelivered": 0, "clicksBreakdown": [], "costBreakdown": [] },
    "templates": [
      {
        "templateId": "1560534655590931",
        "summary": { "sent": 500, "delivered": 465, "read": 0, "clicked": 0, "deliveredRate": 0.93, "readRate": 0, "clickRate": 0, "amountSpent": 0, "costPerDelivered": 0, "clicksBreakdown": [], "costBreakdown": [] },
        "series": [
          { "periodStart": "2026-08-12T00:00:00+00:00", "periodEnd": "2026-08-13T00:00:00+00:00", "sent": 500, "delivered": 465, "read": 0, "clicked": 0, "deliveredRate": 0.93, "readRate": 0, "clickRate": 0, "amountSpent": 0, "isPending": false, "additionalMetrics": { "website_purchases": 34 }, "clicksBreakdown": [], "costBreakdown": [] }
        ]
      }
    ]
  },
  "isSuccess": true
}

Demo 5 — WABA timezone buckets

GET /api/v1/wa/app_7poyXj8GXuv76e/templates/metrics?templateId=842802041844912&useWabaTimezone=true
Authorization: Bearer sk_...

The response echoes the applied choice so you can label your charts correctly:

{ "data": { "granularity": "DAILY", "usesWabaTimezone": true, "periodStart": "2026-07-14T00:00:00+00:00", "periodEnd": "2026-08-13T23:59:59+00:00", "summary": { "sent": 1200, "delivered": 1140, "read": 860, "clicked": 210, "deliveredRate": 0.95, "readRate": 0.7544, "clickRate": 0.1842, "amountSpent": 18.42, "costPerDelivered": 0.0162, "clicksBreakdown": [], "costBreakdown": [] }, "templates": [] }, "isSuccess": true }

Demo 6 — error: more than 10 template IDs → 422

GET /api/v1/wa/app_7poyXj8GXuv76e/templates/metrics?templateId=1&templateId=2&templateId=3&templateId=4&templateId=5&templateId=6&templateId=7&templateId=8&templateId=9&templateId=10&templateId=11
Authorization: Bearer sk_...

{ "errors": { "code": "META_104", "group": "LIMIT_EXCEEDED", "description": "Too many templates requested. A maximum of 10 template IDs can be queried per request." }, "isSuccess": false }

Demo 7 — error: range wider than 90 days → 422

GET /api/v1/wa/app_7poyXj8GXuv76e/templates/metrics?templateId=842802041844912&startDate=2026-01-01T00:00:00&endDate=2026-08-13T00:00:00
Authorization: Bearer sk_...

{ "errors": { "code": "META_105", "group": "VALIDATION", "description": "The requested date range is too large. The maximum allowed range is 90 days." }, "isSuccess": false }

Errors

object

Error details with code, group, and description; isSuccess is false.

Auth / tenant

HTTP	Code	When
401	`ORGANIZATION_SECRET_010`	Secret key is missing.
401	`ORGANIZATION_SECRET_011`	Secret key is invalid.
404	`APPLICATION_004`	`app_id` does not belong to the organization.

Request validation

HTTP	Code	Group	When
422	`VAL_019`	`VALIDATION`	`endDate <= startDate` (invalid date range).
422	`META_104`	`LIMIT_EXCEEDED`	More than 10 distinct `templateId` values.
422	`META_105`	`VALIDATION`	The range exceeds 90 days.
400	`META_102`	`VALIDATION`	No usable `templateId` (all values blank).
422	`VAL_*` (FastAPI validation)	`VALIDATION`	`templateId` missing entirely, invalid `granularity` / `metricType` / `productType` enum value, unparseable `startDate` / `endDate`.

Meta-side

HTTP	Code	When
401	`META_099`	Token invalid/expired (190).
403	`META_100`	Permission denied (10 / 200–299).
429	`META_101`	Rate limit (4 / 80007).
400	`META_102`	Invalid parameter (100).
409	`META_103`	Template analytics is not enabled for this WABA — enable insights and retry.
409	`META_106`	Template analytics is not available for this WABA yet.
422	`META_107`	None of the given template IDs is valid for this WABA.
502	`META_098`	General/fallback analytics error.

Example error responses:

{ "errors": { "code": "VAL_019", "group": "VALIDATION", "description": "Invalid date range." }, "isSuccess": false }

{ "errors": { "code": "META_103", "group": "CONFLICT", "description": "Template analytics is not enabled for this WhatsApp Business Account. Enable insights and try again." }, "isSuccess": false }

{ "errors": { "code": "META_107", "group": "VALIDATION", "description": "None of the specified template IDs is valid for this WhatsApp Business Account." }, "isSuccess": false }

Getting Started

Analytics

Application

Template

Media

Developers

Reference

What it does

Endpoint

Headers

Path parameters

Query parameters

Response

Examples

Errors

Auth / tenant

Request validation

Meta-side

​What it does

​Endpoint

​Headers

​Path parameters

​Query parameters

​Response

​Examples

​Errors

​Auth / tenant

​Request validation

​Meta-side

What it does

Endpoint

Headers

Path parameters

Query parameters

Response

Examples

Errors

Auth / tenant

Request validation

Meta-side