Customer.io
v1.0.0
OpenAPI 3.1.0

Get campaign action metrics

US region

Client Libraries
Shell Curl

Get campaign action metrics

​

Returns metrics for an individual action, both in total and 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.

Multi-language messages

If the action is a multi-language message, the response also includes a language_variants object with a breakdown for each language variant, keyed by the variant's action ID. You get that breakdown whether you send version=1 or version=2.

In this case, metric is the total across every variant. If you sum metrics across all of a campaign's actions, skip actions that return language_variants or you will count those messages twice—once in the multi-language action's total, and again in each variant's own action.

Path Parameters
  • campaign_id
    Type: integer
    required

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

  • action_id
    Type: integer
    required

    The action you want to lookup or act on.

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}/actions/{action_id}/metrics
curl 'https://api.customer.io/v1/campaigns/3/actions/1/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
      ]
    }
  },
  "language_variants": {
    "additionalProperty": {
      "language": "es",
      "default": false,
      "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 action metrics by series, where each increment is based on the res in your request. For a multi-language message, also returns a per-variant breakdown in language_variants.