---
title: "Analytics API: retrieve your WhatsApp statistics"
description: "Retrieve through the API the attributed revenue, cost, ROAS and funnel of your account, campaigns and automations, for your dashboards or BI tool."
url: https://help.getkanal.com/en/articles/140-analytics-api-retrieve-your-whatsapp-statistics
collection: "API"
updated: 2026-11-09
language: en
alternates: [fr-fr]
---

# Analytics API: retrieve your WhatsApp statistics

Retrieve through the API the attributed revenue, cost, ROAS and funnel of your account, campaigns and automations, for your dashboards or BI tool.

The Analytics API gives you, programmatically, the figures from Kanal's Home page: revenue and orders attributed to WhatsApp, message cost, ROAS and the engagement funnel. You can fetch them for the whole account, or for a specific campaign or automation. Use it for example to feed an internal dashboard or a BI tool (Looker Studio, Power BI, Google Sheets...).

## Prerequisites

-   An **active Kanal subscription**: without one, every call returns 403.
    
-   Your **API key**, the same as for the rest of the API, sent in the `Authorization: Bearer <your API key>` header. The key gives access to the figures of the whole Kanal account it was created in.
    

To create a key, see [API authentication and keys](https://help.getkanal.com/en/articles/14.md).

## The 6 endpoints

<table style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p><strong>Method</strong></p></th><th colspan="1" rowspan="1"><p><strong>Path</strong></p></th><th colspan="1" rowspan="1"><p><strong>Purpose</strong></p></th></tr><tr><td colspan="1" rowspan="1"><p>GET</p></td><td colspan="1" rowspan="1"><p><code>/api/v1/stats/overview</code></p></td><td colspan="1" rowspan="1"><p>Account KPIs: revenue, cost, ROAS, funnel, split by source, top 5 campaigns and automations</p></td></tr><tr><td colspan="1" rowspan="1"><p>GET</p></td><td colspan="1" rowspan="1"><p><code>/api/v1/stats/chart</code></p></td><td colspan="1" rowspan="1"><p>Daily values of one metric</p></td></tr><tr><td colspan="1" rowspan="1"><p>GET</p></td><td colspan="1" rowspan="1"><p><code>/api/v1/stats/campaigns/{campaign_id}</code></p></td><td colspan="1" rowspan="1"><p>Stats of one campaign</p></td></tr><tr><td colspan="1" rowspan="1"><p>GET</p></td><td colspan="1" rowspan="1"><p><code>/api/v1/stats/automations/{automation_id}</code></p></td><td colspan="1" rowspan="1"><p>Stats of one automation, with a per-step breakdown</p></td></tr><tr><td colspan="1" rowspan="1"><p>GET</p></td><td colspan="1" rowspan="1"><p><code>/api/v1/campaigns</code></p></td><td colspan="1" rowspan="1"><p>List of campaigns (with their id)</p></td></tr><tr><td colspan="1" rowspan="1"><p>GET</p></td><td colspan="1" rowspan="1"><p><code>/api/v1/automations</code></p></td><td colspan="1" rowspan="1"><p>List of automations (with their id)</p></td></tr></tbody></table>

The IDs for the stats routes come from the two lists, or from the `top` block of the account overview.

## Example

```bash
curl "https://api.getkanal.com/api/v1/stats/overview?time_range=last_30_days&compared_to=previous_period" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Choose the period

Every stats route accepts the same parameters:

-   `time_range`: `today`, `week_to_date`, `last_7_days`, `month_to_date`, `last_30_days` (default), `last_3_months`, `last_6_months`, `year_to_date`, `all_time` or `custom`.
    
-   `start_date` and `end_date` (YYYY-MM-DD format), only with `time_range=custom`.
    
-   `compared_to`: `previous_period`, `previous_year` or `custom` (with `compare_start_date` and `compare_end_date`). Each metric then gets its previous value and its change in %.
    

Days are counted in the account time zone, both bounds included. Each response echoes the period actually used.

## Available metrics

-   **Account overview**: revenue, ROAS, total and marketing cost, conversations, attributed orders, revenue per recipient, delivered messages, funnel (delivered, read, interactions with clicks and replies, converted), revenue split between campaigns, automations and AI Agent, top 5 campaigns and automations.
    
-   **Time series**: one metric per day with the `metric` parameter: `revenue` (default), `orders`, `conversations`, `cost`, `delivered`, `read`, `roas` or `conversion_rate`. Days without data may be missing: count them as 0.
    
-   **Campaign**: revenue, ROAS, orders, cost, delivered messages, conversion rate, revenue per recipient and funnel. Revenue is counted on the order day: for a campaign's full result, pick a period that starts on the send day and covers the attribution window.
    
-   **Automation**: the same figures, plus the per-step breakdown (`nodes`): revenue, orders, ROAS, messages sent, delivered, read, clicked and contacts that entered the step.
    

## Calculation rules

-   **Attribution**: figures follow your Settings > Attribution configuration (5-day window and "Delivered" basis by default). They match the figures shown in Kanal.
    
-   **Currency**: revenue and cost are always in euros, whatever the store currency.
    
-   **Freshness**: attribution is rebuilt every 15 minutes, the last 30 minutes may still change. No need to poll the API more often than every 15 minutes.
    

## Limit and errors

60 requests per minute per API key, shared across the 6 routes. Above that, the API returns 429 with a `Retry-After` header.

<table style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p><strong>Code</strong></p></th><th colspan="1" rowspan="1"><p><strong>Cause</strong></p></th></tr><tr><td colspan="1" rowspan="1"><p>401</p></td><td colspan="1" rowspan="1"><p>Missing or invalid API key</p></td></tr><tr><td colspan="1" rowspan="1"><p>403</p></td><td colspan="1" rowspan="1"><p>No active subscription</p></td></tr><tr><td colspan="1" rowspan="1"><p>404</p></td><td colspan="1" rowspan="1"><p>Unknown campaign or automation, or one from another account</p></td></tr><tr><td colspan="1" rowspan="1"><p>422</p></td><td colspan="1" rowspan="1"><p>Invalid period or metric parameter</p></td></tr><tr><td colspan="1" rowspan="1"><p>429</p></td><td colspan="1" rowspan="1"><p>Too many requests</p></td></tr></tbody></table>

> **Info:** Full technical documentation, with every response field: [developers.getkanal.com/docs/analytics](https://developers.getkanal.com/docs/analytics).