Customer.io
v1.0.0
OpenAPI 3.1.0

Get campaign metrics

US region

Client Libraries
Shell Curl

Get campaign metrics

​

Returns metrics for an individual campaign as a series of counts, oldest first—the 0-index of any result is the oldest point in the window.

We recommend version 2. Send version=2. It accepts an explicit start, end, and res, reported in the tz you choose. Without it, the endpoint answers with version 1 behavior instead: a window built from period and steps, always in Eastern time.

Version 1 can't return fewer than 2 steps of any period. ?period=days&steps=1 means two days—the 48 hours before the request—and ?period=days&steps=0 returns the maximum for the period, the same as ?period=days&steps=45.

Path Parameters
  • campaign_id
    Type: integer
    required

    The ID of the campaign that you want to trigger or return information about.

Query Parameters
  • version
    Type: stringenum

    Send 2. We recommend version 2: it takes an explicit window (start, end, and res) in the time zone you pass as tz.

    Any other value, including leaving the parameter off, uses version 1: a window derived from period and steps, always in Eastern time.

    values
    • 1
    • 2
  • res
    Type: stringenum

    Version 2. Required when you send version=2. Sets the increment for each point in the series—hourly, daily, weekly, or monthly.

    values
    • hours
    • hourly
    • days
    • daily
    • weeks
    • weekly
    • months
    • monthly
  • start
    Type: integerFormat: unix timestamp

    Version 2. Required when you send version=2. The unix timestamp for the beginning of your metrics.

  • end
    Type: integerFormat: unix timestamp

    Version 2. Required when you send version=2. The unix timestamp for the end of your metrics. Limited to 10 years from the start parameter.

  • tz
    Type: string

    Version 2. The time zone for the window you request. Defaults to UTC. Use the region format.

  • period
    Type: stringenum
    deprecated

    Version 1. The unit of time for your report. Send version=2 and set res instead.

    values
    • hours
    • days
    • weeks
    • months
  • steps
    Type: integer
    deprecated

    Version 1. The number of periods you want to return. Defaults to the maximum available, or 12 if the period is in months. Maximums are 24 hours, 45 days, 12 weeks, or 121 months. Days start at 00:00 EST, weeks at 00:00 EST on Sunday, months at 00:00 EST on the 1st. Send version=2 and set start and end instead.

  • type
    Type: stringenum

    The type of item you want to return metrics for. When empty, the response contains metrics for all possible types.

    values
    • email
    • webhook
    • twilio
    • whatsapp
    • slack
    • push
    • in_app
    • live_notification
Responses
  • application/json
  • 400

    The campaignID or actionID is invalid.

  • 404

    The campaign and/or action do not exist.

  • 429

    Your request is over the 10-per-second limit.

Request Example for get/v1/campaigns/{campaign_id}/metrics
curl 'https://api.customer.io/v1/campaigns/3/metrics?version=2&res=days&start=1735718400&end=1735804800&type=email' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "start": "2025-01-01 00:00:00 +0000 UTC",
  "end": "2025-01-02 00:00:00 +0000 UTC",
  "res": "days",
  "metric": {
    "series": {
      "attempted": [
        1
      ],
      "bounced": [
        1
      ],
      "clicked": [
        1
      ],
      "human_clicked": [
        1
      ],
      "machine_clicked": [
        1
      ],
      "converted": [
        1
      ],
      "created": [
        1
      ],
      "deferred": [
        1
      ],
      "delivered": [
        1
      ],
      "drafted": [
        1
      ],
      "failed": [
        1
      ],
      "opened": [
        1
      ],
      "human_opened": [
        1
      ],
      "prefetch_opened": [
        1
      ],
      "sent": [
        1
      ],
      "spammed": [
        1
      ],
      "suppressed": [
        1
      ],
      "undeliverable": [
        1
      ],
      "topic_unsubscribed": [
        1
      ],
      "unsubscribed": [
        1
      ],
      "replied": [
        1
      ],
      "untracked": [
        1
      ],
      "open_untracked": [
        1
      ],
      "link_untracked": [
        1
      ],
      "tracking_consent_granted": [
        1
      ],
      "tracking_consent_denied": [
        1
      ]
    }
  }
}

Returns campaign metrics by series based on the parameters of the request.