Retrieve a campaign's metricsMenu

Retrieve a campaign's metrics

GET/v1/campaigns/{id}/metrics

Requires an API key with the campaigns:read scope. About keys and scopes

Works with integration, agent and partner keys.

Returns how a campaign did over its whole life. People-level numbers sit at the top: recipientCount, and the conversions and credited revenue its messages drove (gross, before refunds; zeros without conversion goals). Message counters sit under email and push, never added together, null for a channel the campaign does not send; push device outcomes are under push.devices. Email's opened includes machine opens (openedByMachine); a machine's click counts in neither clicked nor opened. Counters keep moving after a send completes, as opens, clicks and bounces arrive.

Path parameters

idstringrequired

The campaign's id.

uuid

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Returns

Returns 200 OK with a CampaignMetrics in data. Otherwise returns an error; Errors lists every code and which to retry.

campaignIdstringrequired

uuid

recipientCountintegerrequired

People the campaign went to, each counted once across channels.

min 0

conversionsintegerrequired

Conversions of the campaign's goals that its messages drove; 0 without goals.

min 0

revenueMoney[]required

Credited revenue per goal currency, never converted: what conversions a message drove were worth, gross, before refunds and cancellations.

2 child attributes

currencystring | nullrequired: The currency, an ISO 4217 code; null when none was named.
valuenumberrequired: The amount in that currency.

revenueWithheldbooleanrequired

True when revenue leaves out the value of a goal whose value property is a masked attribute this viewer may not see; its conversions are still counted.

emailobject | nullrequired

Email message counters; null when the campaign sends no email.

16 child attributes

queuedintegerrequired

Messages waiting to be sent.

min 0

sendingintegerrequired

Messages being handed to the provider.

min 0

skippedintegerrequired

Messages not sent; see skippedByReason.

min 0

sentintegerrequired

Messages the provider accepted, whatever happened next: a delivered, bounced or failed message still counts here.

min 0

failedintegerrequired

Messages that could not be sent or failed after sending.

min 0

deliveredintegerrequired

Messages confirmed delivered, including any later marked as spam.

min 0

bouncedintegerrequired

Messages in status bounced, test sends to [email protected] included (see simulated); deliverabilityHealth counts recorded bounces of real sends only.

min 0

complainedintegerrequired

Messages in status complained, test sends to [email protected] included (see simulated).

min 0

openedintegerrequired

Messages opened at least once.

min 0

openedByMachineintegerrequired

Of opened, those only a machine opened: a mail app fetched its images with no reader (Apple Mail Privacy Protection, Gmail's prefetch on delivery) or a mail security scanner checked it. Clicks are unaffected.

min 0

clickedintegerrequired

Messages with a link clicked at least once, by a person.

min 0

clickedByMachineintegerrequired

Messages whose links a machine followed: a mail security scanner checking them on delivery, a link preview. The machine's click counts in neither clicked nor opened (a person's click on the same message still does), and no webhook or journey sees it.

min 0

unsubscribedintegerrequired

Recipients who opted out through this campaign's link.

min 0

simulatedintegerrequired

Test sends whose outcome was acted out: those to delivered@, bounce@ or [email protected] (the transactional guide's "Test addresses"). These counts go by message status, so they include them; deliverabilityHealth leaves them out.

min 0

totalintegerrequired

All messages created. sent and delivered overlap the other counts, so they do not add up to it; byStatus does.

min 0

byStatusmap<string, integer>required

Each message once, by where it is now, summing to total: the delivery breakdown. A delivered message later marked as spam is complained here, while delivered above still counts it.

keys: one of queued, sending, skipped, sent, failed, delivered, bounced, complained · values: min 0

deliverabilityHealthobject | nullrequired

Advisory bounce and complaint health of the campaign's email, judged on the same lines and minimums as deliverabilityHealth on getOverviewReport; null when the campaign sends no email. It reads real sends only: test sends (email.simulated) are left out, though email.bounced and email.complained, counted by status, include them.

8 child attributes

bandstringrequired

insufficient_data until the sample and feedback coverage minimums are met; then the highest line the bounce or complaint ratio reaches.

one of insufficient_data, healthy, watch, critical

limitsDeliverabilityLimitsrequired

Where the bands start, the workspace's own lines: watch where its admins are warned, critical where its marketing email pauses. The pause is judged on all of the workspace's marketing email over the last 24 hours (or week, for a small sender), not on one report.

2 child attributes

watchobjectrequired

2 child attributes

bounceRationumberrequired

A ratio from 0 to 1: 0.05 is 5%.

min 0 · max 1

complaintRationumberrequired

A ratio from 0 to 1: 0.05 is 5%.

min 0 · max 1

criticalobjectrequired

2 child attributes

bounceRationumberrequired

A ratio from 0 to 1: 0.05 is 5%.

min 0 · max 1

complaintRationumberrequired

A ratio from 0 to 1: 0.05 is 5%.

min 0 · max 1

bounceRationumber | nullrequired

Recorded bounces per sent email, the figure the band compares with limits; null while sampleSize is 0.

min 0 · max 1

complaintRationumber | nullrequired

Recorded complaints per sent email, the figure the band compares with limits; null while sampleSize is 0.

min 0 · max 1

sampleSizeintegerrequired

Sent emails the band is judged on: real sends only, with test sends that act an outcome out (delivered@, bounce@, [email protected]) left out.

min 0

minimumSampleSizeintegerrequired

The fewest emails (sampleSize) the band is judged on, currently 100: below it the band is insufficient_data.

min 1

feedbackCoveragenumber | nullrequired

Share of the sample whose outcome (delivered, bounced or complained) is known; null before any email is sent.

min 0 · max 1

minimumFeedbackCoveragenumberrequired

The least feedbackCoverage the band is judged on, currently 0.95: below it the band is insufficient_data, as bounce and complaint reports are still arriving.

min 0 · max 1

pushobject | nullrequired

Push message counters; null when the campaign sends no push.

10 child attributes

queuedintegerrequired

Messages waiting to be sent.

min 0

sendingintegerrequired

Messages being handed to the provider.

min 0

skippedintegerrequired

Messages not sent; see skippedByReason.

min 0

sentintegerrequired

Messages the provider accepted, whatever happened next: a delivered, bounced or failed message still counts here.

min 0

failedintegerrequired

Messages that could not be sent or failed after sending.

min 0

byStatusobjectrequired

Each message once, by where it is now, summing to total.

5 child attributes

queuedintegerrequired: min 0
sendingintegerrequired: min 0
skippedintegerrequired: min 0
sentintegerrequired: min 0
failedintegerrequired: min 0

openedintegerrequired

Messages the app reported opened at least once.

min 0

clickedintegerrequired

Messages the app reported tapped through to a link at least once.

min 0

totalintegerrequired

All messages created.

min 0

devicesobjectrequired

Device outcomes: one push message goes to every device its contact has, so these count devices, not messages, and never add to the counters beside them.

10 child attributes

pendingintegerrequired

Devices not yet attempted.

min 0

startedintegerrequired

Devices being sent to now.

min 0

acceptedintegerrequired

Devices the push service accepted.

min 0

invalidintegerrequired

Devices whose registration is no longer valid.

min 0

rejectedintegerrequired

Devices the push service permanently refused.

min 0

retryableintegerrequired

Devices that failed temporarily and will be retried.

min 0

unknownintegerrequired

Devices whose outcome could not be determined.

min 0

skippedintegerrequired

Devices not sent to.

min 0

totalintegerrequired

All devices targeted.

min 0

byPlatformobjectrequired

3 child attributes

iosobjectoptional

9 child attributes

pendingintegerrequired

Devices not yet attempted.

min 0

startedintegerrequired

Devices being sent to now.

min 0

acceptedintegerrequired

Devices the push service accepted.

min 0

invalidintegerrequired

Devices whose registration is no longer valid.

min 0

rejectedintegerrequired

Devices the push service permanently refused.

min 0

retryableintegerrequired

Devices that failed temporarily and will be retried.

min 0

unknownintegerrequired

Devices whose outcome could not be determined.

min 0

skippedintegerrequired

Devices not sent to.

min 0

totalintegerrequired

All devices targeted.

min 0

androidobjectoptional

9 child attributes

pendingintegerrequired

Devices not yet attempted.

min 0

startedintegerrequired

Devices being sent to now.

min 0

acceptedintegerrequired

Devices the push service accepted.

min 0

invalidintegerrequired

Devices whose registration is no longer valid.

min 0

rejectedintegerrequired

Devices the push service permanently refused.

min 0

retryableintegerrequired

Devices that failed temporarily and will be retried.

min 0

unknownintegerrequired

Devices whose outcome could not be determined.

min 0

skippedintegerrequired

Devices not sent to.

min 0

totalintegerrequired

All devices targeted.

min 0

webobjectoptional

9 child attributes

pendingintegerrequired

Devices not yet attempted.

min 0

startedintegerrequired

Devices being sent to now.

min 0

acceptedintegerrequired

Devices the push service accepted.

min 0

invalidintegerrequired

Devices whose registration is no longer valid.

min 0

rejectedintegerrequired

Devices the push service permanently refused.

min 0

retryableintegerrequired

Devices that failed temporarily and will be retried.

min 0

unknownintegerrequired

Devices whose outcome could not be determined.

min 0

skippedintegerrequired

Devices not sent to.

min 0

totalintegerrequired

All devices targeted.

min 0

skippedByReasonmap<string, integer>required

Skipped messages by reason, such as message_limit or expired, across channels; each channel's skipped is its part.

values: min 0

abTestobject | nullrequired

The test group's results by version; the rest of the audience is in the totals only. null without an A/B test.

2 child attributes

winnerinteger | nullrequired

The winning version, once picked.

min 1

versionsAbTestVersionResult[]required

Each version in the test group, version 1 first. The winner is picked on open and click rates over delivered (over sent until any version has a delivery) and conversions over sent.

6 child attributes

versionintegerrequired

min 1

sentintegerrequired

Test messages handed to the provider.

min 0

deliveredintegerrequired

min 0

openedintegerrequired

Test messages a person opened; machine opens are left out.

min 0

clickedintegerrequired

min 0

conversionsintegerrequired

Recipients who reached the test's conversion goal; 0 without one.

min 0

curl https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/metrics \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/metrics', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/metrics",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/metrics", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.kirora.io/v1/campaigns/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/metrics");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 200

{
  "data": {
    "campaignId": "0192f3d3-5e6f-7071-8c83-9e0f1a2b3c4d",
    "recipientCount": 2455,
    "conversions": 41,
    "revenue": [
      {
        "currency": "USD",
        "value": 2870.5
      }
    ],
    "revenueWithheld": false,
    "email": {
      "queued": 0,
      "sending": 0,
      "skipped": 12,
      "sent": 2440,
      "failed": 3,
      "delivered": 2391,
      "bounced": 38,
      "complained": 2,
      "opened": 1130,
      "openedByMachine": 412,
      "clicked": 341,
      "clickedByMachine": 29,
      "unsubscribed": 6,
      "simulated": 0,
      "total": 2455,
      "byStatus": {
        "queued": 0,
        "sending": 0,
        "skipped": 12,
        "sent": 11,
        "failed": 3,
        "delivered": 2389,
        "bounced": 38,
        "complained": 2
      }
    },
    "deliverabilityHealth": {
      "band": "healthy",
      "limits": {
        "watch": {
          "bounceRatio": 0.02,
          "complaintRatio": 0.0005
        },
        "critical": {
          "bounceRatio": 0.03,
          "complaintRatio": 0.0008
        }
      },
      "bounceRatio": 0.004,
      "complaintRatio": 0,
      "sampleSize": 2455,
      "minimumSampleSize": 100,
      "feedbackCoverage": 0.99,
      "minimumFeedbackCoverage": 0.95
    },
    "push": null,
    "skippedByReason": {
      "message_limit": 12
    },
    "abTest": null
  }
}