List campaign reportsMenu

List campaign reports

GET/v1/reports/campaigns

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

Works with integration, agent and partner keys.

Available on plans with advanced reports. Plans

Lists campaign performance over a window. One row per campaign with a marketing message in the window, including a campaign none of whose messages were sent: its email shows as failed or skipped. Counts are send cohorts like the overview: email by the time it was sent, email never sent and push by the time it was queued, and later feedback revises them. Journey and transactional messages are not here (see the journey and transactional reports), so these rows can sum to less than the overview. Conversions are those whose source message was sent in the window, and revenue is summed per goal currency, never converted. Rates are fractions; null means no denominator, and sorts below every rate. sent sorts by email sent. Without from and to, the window is the last 30 days ending today. Needs a plan with advanced reports: without one, 403 PLAN_FEATURE_UNAVAILABLE.

Query parameters

limitintegeroptional

How many items a page holds: 1 to 100, 20 by default.

min > 0 · max 100 · default 20

cursorstringoptional

Where the page starts: the previous page's meta.pagination.nextCursor. Omit it for the first page, and send the same filters with it.

1–2,048 characters

fromstringoptional

Start of the window, inclusive: a date-time, or a date meaning the start of that day in the workspace timezone. Give with to; omit both for the last 30 days.

tostringoptional

End of the window, exclusive, in the same forms. To include a whole last day, pass the day after it: from=2026-10-01&to=2026-10-08 covers 1 to 7 October. No later than the end of today; a window touches at most 366 days. Give with from.

sortstringoptional

A field ascending, or -field descending. Rates with no denominator sort last.

one of firstAttemptedAt, sent, openRate, clickRate, bounceRate, unsubscribeRate, conversions, -firstAttemptedAt, -sent, -openRate, -clickRate, -bounceRate, -unsubscribeRate, -conversions · default "-firstAttemptedAt"

tagstringoptional

Only campaigns carrying this tag, its name matched without case: "everything tagged Black Friday".

1–64 characters

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 list of CampaignPerformance objects in data, and the next page's cursor in meta (see pagination). Otherwise returns an error; Errors lists every code and which to retry.

campaignIdstringrequired

uuid

namestringrequired

statusstringrequired

one of draft, scheduled, sending, testing, sent, cancelled

channelsstring[]required

The channels the campaign targets.

firstAttemptedAtstringrequired

The campaign's first message in the window: when it was sent, or queued for one never sent. Not the campaign schedule.

date-time

emailobjectrequired

Email counts and rates for the window. sent covers only email the provider accepted.

11 child attributes

sentintegerrequired

min 0

deliveredintegerrequired

min 0

openedintegerrequired

Opened at least once, including openedByMachine.

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.

min 0

clickedintegerrequired

With a link clicked by a person.

min 0

failedintegerrequired

Not delivered, with no bounce or complaint: refused before sending, or failed after it. Each message's failure.reason says why.

min 0

skippedintegerrequired

Stopped before sending by a guard (no consent, suppressed, no address). Not in sent.

min 0

bouncedintegerrequired

min 0

complainedintegerrequired

min 0

unsubscribedintegerrequired

min 0

ratesEmailRatesrequired

Email rates as fractions: delivery over sent; bounce and complaint over real sends (sent less simulated where the counts give it), as deliverabilityHealth judges them; open, click and unsubscribe over delivered. null when there is no denominator.

6 child attributes

deliverynumber | nullrequired: min 0
opennumber | nullrequired: min 0
clicknumber | nullrequired: min 0
bouncenumber | nullrequired: min 0
complaintnumber | nullrequired: min 0
unsubscribenumber | nullrequired: min 0

pushobjectrequired

Push counts for the window.

4 child attributes

sentintegerrequired: min 0
failedintegerrequired: min 0
openedintegerrequired: min 0
clickedintegerrequired: min 0

conversionsintegerrequired

Goal conversions whose source message was sent in the window.

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.

curl https://api.kirora.io/v1/reports/campaigns \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/reports/campaigns', {
  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, meta } = await response.json();
// meta.pagination.nextCursor is the next page's `cursor`, and null on the last page.

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/reports/campaigns",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
body = response.json()
data = body["data"]
next_cursor = body["meta"]["pagination"]["nextCursor"]
# next_cursor is the next page's `cursor`, and None on the last page.

package main

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

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/reports/campaigns", 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"`
		Meta struct {
			Pagination struct {
				NextCursor *string `json:"nextCursor"`
			} `json:"pagination"`
		} `json:"meta"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
	// out.Meta.Pagination.NextCursor is the next page's `cursor`, and nil on the last page.
}

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/reports/campaigns");
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");
var nextCursor = document.RootElement.GetProperty("meta").GetProperty("pagination").GetProperty("nextCursor");
// nextCursor is the next page's `cursor`, and null on the last page.

Response · 200

{
  "data": [
    {
      "campaignId": "0192f3d3-5e6f-7071-8c83-9e0f1a2b3c4d",
      "name": "October newsletter",
      "status": "sent",
      "channels": [
        "email"
      ],
      "firstAttemptedAt": "2026-10-01T09:31:00.000Z",
      "email": {
        "sent": 1000,
        "delivered": 980,
        "opened": 410,
        "openedByMachine": 120,
        "clicked": 96,
        "failed": 3,
        "skipped": 20,
        "bounced": 12,
        "complained": 1,
        "unsubscribed": 6,
        "rates": {
          "delivery": 0.98,
          "open": 0.418,
          "click": 0.098,
          "bounce": 0.012,
          "complaint": 0.001,
          "unsubscribe": 0.006
        }
      },
      "push": {
        "sent": 0,
        "failed": 0,
        "opened": 0,
        "clicked": 0
      },
      "conversions": 21,
      "revenue": [
        {
          "currency": "USD",
          "value": 964.5
        }
      ],
      "revenueWithheld": false
    }
  ],
  "meta": {
    "pagination": {
      "limit": 20,
      "nextCursor": null
    },
    "window": {
      "from": "2026-09-07T23:00:00.000Z",
      "to": "2026-10-07T23:00:00.000Z",
      "timezone": "Europe/London"
    }
  }
}