Retrieve the performance overviewMenu

Retrieve the performance overview

GET/v1/reports/overview

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

Works with integration, agent and partner keys.

Returns how the workspace did in a window: marketing email in email and marketing push in push, never added together, each against the period before. Email counts are send cohorts (by the day it was sent), push by the day it was queued, and later feedback revises them. Bounce and complaint counts are durable first-occurrence facts, not current statuses. conversions are the goal conversions a message drove, with their credited revenue, gross; refunds sums every refund in the window beside it. deliverabilityHealth is an advisory band from the workspace's own bounce and complaint rates against Kirora's warning and pause lines, not the sending provider's reputation. Rates are fractions; null means no denominator. Days are calendar days in the workspace timezone (timezone, set in workspace settings); the first and last may be partial. Without from and to, the window is the last 30 days ending today.

Query parameters

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.

tagstringoptional

Only email, push and conversions from campaigns and journeys carrying this tag, its name matched without case: "how did everything tagged Black Friday do". Refunds are not filtered: no message is linked to them.

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 an Overview in data. Otherwise returns an error; Errors lists every code and which to retry.

generatedAtstringrequired

date-time

timezonestringrequired

The workspace timezone that date bounds and series days are in.

fromstringrequired

Start of the window, inclusive.

date-time

tostringrequired

End of the window, exclusive.

date-time

previousPeriodobjectrequired

The equal-length period just before the window.

2 child attributes

fromstringrequired

Start of the window, inclusive.

date-time

tostringrequired

End of the window, exclusive.

date-time

emailobjectrequired

Marketing email from campaigns and journeys, by the day it was sent; failed and skipped email that never reached the provider counts on the day it was queued. sent covers only email the provider accepted.

4 child attributes

currentOverviewCountsrequired

Counts in the window.

13 child attributes

sentintegerrequired

deliveredintegerrequired

openedintegerrequired

Opened at least once, including openedByMachine: the open rate counts those too.

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.

clickedintegerrequired

With a link clicked by a person.

simulatedintegerrequired

Of sent, test sends whose outcome was acted out: those to delivered@, bounce@ or [email protected] (the transactional guide's "Test addresses"). Counted in sent and delivered; never in bounced, complained, feedbackObserved, the bounce and complaint rates or deliverabilityHealth.

min 0

feedbackObservedintegerrequired

Of the real sends in sent, those whose delivery, bounce or complaint is known.

failedintegerrequired

Not delivered, with no bounce or complaint: refused before sending (counted on the day it was queued) or failed after it (on the day it was sent, and also in sent). failure.reason on each message says why.

failedBeforeSendingintegerrequired

Of failed, those refused before reaching the provider, on the day they were queued. Not in sent, like skipped, so sent + failedBeforeSending + skipped counts each message once.

skippedintegerrequired

Stopped before sending by a guard (no consent, suppressed, no address), on the day it was queued. Not in sent.

bouncedintegerrequired

complainedintegerrequired

unsubscribedintegerrequired

Recipients who opted out through the email's own link.

previousOverviewCountsrequired

Counts in the previous period.

13 child attributes

sentintegerrequired

deliveredintegerrequired

openedintegerrequired

Opened at least once, including openedByMachine: the open rate counts those too.

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.

clickedintegerrequired

With a link clicked by a person.

simulatedintegerrequired

min 0

feedbackObservedintegerrequired

Of the real sends in sent, those whose delivery, bounce or complaint is known.

failedintegerrequired

failedBeforeSendingintegerrequired

Of failed, those refused before reaching the provider, on the day they were queued. Not in sent, like skipped, so sent + failedBeforeSending + skipped counts each message once.

skippedintegerrequired

Stopped before sending by a guard (no consent, suppressed, no address), on the day it was queued. Not in sent.

bouncedintegerrequired

complainedintegerrequired

unsubscribedintegerrequired

Recipients who opted out through the email's own link.

deltaOverviewCountsrequired

current minus previous.

13 child attributes

sentintegerrequired

deliveredintegerrequired

openedintegerrequired

Opened at least once, including openedByMachine: the open rate counts those too.

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.

clickedintegerrequired

With a link clicked by a person.

simulatedintegerrequired

min 0

feedbackObservedintegerrequired

Of the real sends in sent, those whose delivery, bounce or complaint is known.

failedintegerrequired

failedBeforeSendingintegerrequired

Of failed, those refused before reaching the provider, on the day they were queued. Not in sent, like skipped, so sent + failedBeforeSending + skipped counts each message once.

skippedintegerrequired

Stopped before sending by a guard (no consent, suppressed, no address), on the day it was queued. Not in sent.

bouncedintegerrequired

complainedintegerrequired

unsubscribedintegerrequired

Recipients who opted out through the email's own link.

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

Marketing push, by the day it was queued.

3 child attributes

currentOverviewPushCountsrequired

4 child attributes

sentintegerrequired
failedintegerrequired
openedintegerrequired
clickedintegerrequired

previousOverviewPushCountsrequired

4 child attributes

sentintegerrequired
failedintegerrequired
openedintegerrequired
clickedintegerrequired

deltaOverviewPushCountsrequired

4 child attributes

sentintegerrequired
failedintegerrequired
openedintegerrequired
clickedintegerrequired

conversionsobjectrequired

Goal conversions a message drove, by when they happened, from email and push alike: a conversion is one order, whichever message gets the credit. An event credited to several campaigns' or journeys' goals counts once here, though each goal's own report counts it. Revenue is summed per goal currency and never converted; goals without a currency share the null row.

4 child attributes

currentintegerrequired

min 0

previousintegerrequired

min 0

revenueobject[]required

Credited revenue per goal currency, gross: before refunds.

3 child attributes

currencystring | nullrequired: The goal currency; null when none.
currentnumberrequired
previousnumberrequired

revenueWithheldbooleanrequired

True when revenue leaves out the value of goals whose value property is a masked attribute this viewer may not see: their conversions are counted, their values are not, here and in each day's revenue.

refundsMoney[]required

All refunds in the window, whether or not a message drove the order: the total of each Order Refunded event (or the workspace's own refund event, set in its key events), per its currency, never converted. Not subtracted from conversions.revenue. Empty when refundsWithheld.

2 child attributes

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

refundsWithheldbooleanrequired

True when refunds is left out because total or currency is a masked attribute this viewer may not see.

deliverabilityHealthDeliverabilityHealthrequired

Advisory bounce and complaint health on the workspace's lines (limits): judged once sampleSize and feedbackCoverage reach their minimums. Bounces and complaints are recorded ones, so a simulated test bounce never counts.

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

seriesobject[]required

One point per calendar day in the window: email and push by the day they were sent, conversions and revenue by the day they happened.

at most 366 items

5 child attributes

startsAtstringrequired

When this day starts in timezone, given as an instant.

date-time

emailOverviewCountsrequired

Email by the day it was sent; email never sent by the day it was queued.

13 child attributes

sentintegerrequired

deliveredintegerrequired

openedintegerrequired

Opened at least once, including openedByMachine: the open rate counts those too.

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.

clickedintegerrequired

With a link clicked by a person.

simulatedintegerrequired

min 0

feedbackObservedintegerrequired

Of the real sends in sent, those whose delivery, bounce or complaint is known.

failedintegerrequired

failedBeforeSendingintegerrequired

Of failed, those refused before reaching the provider, on the day they were queued. Not in sent, like skipped, so sent + failedBeforeSending + skipped counts each message once.

skippedintegerrequired

Stopped before sending by a guard (no consent, suppressed, no address), on the day it was queued. Not in sent.

bouncedintegerrequired

complainedintegerrequired

unsubscribedintegerrequired

Recipients who opted out through the email's own link.

pushOverviewPushCountsrequired

Push by the day it was queued.

4 child attributes

sentintegerrequired
failedintegerrequired
openedintegerrequired
clickedintegerrequired

conversionsintegerrequired

Goal conversions that happened that day, as in conversions.

min 0

revenueMoney[]required

Credited revenue that day per goal currency, never converted; empty when none.

2 child attributes

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

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

const response = await fetch('https://api.kirora.io/v1/reports/overview', {
  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/reports/overview",
    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/reports/overview", 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/reports/overview");
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": {
    "generatedAt": "2026-10-08T12:00:00.000Z",
    "timezone": "Europe/London",
    "from": "2026-09-30T23:00:00.000Z",
    "to": "2026-10-07T23:00:00.000Z",
    "previousPeriod": {
      "from": "2026-09-23T23:00:00.000Z",
      "to": "2026-09-30T23:00:00.000Z"
    },
    "email": {
      "current": {
        "sent": 4000,
        "delivered": 3920,
        "opened": 1640,
        "openedByMachine": 480,
        "clicked": 384,
        "simulated": 0,
        "feedbackObserved": 4000,
        "failed": 12,
        "failedBeforeSending": 8,
        "skipped": 80,
        "bounced": 48,
        "complained": 4,
        "unsubscribed": 24
      },
      "previous": {
        "sent": 3000,
        "delivered": 2940,
        "opened": 1230,
        "openedByMachine": 360,
        "clicked": 288,
        "simulated": 0,
        "feedbackObserved": 3000,
        "failed": 9,
        "failedBeforeSending": 6,
        "skipped": 60,
        "bounced": 36,
        "complained": 3,
        "unsubscribed": 18
      },
      "delta": {
        "sent": 1000,
        "delivered": 980,
        "opened": 410,
        "openedByMachine": 120,
        "clicked": 96,
        "simulated": 0,
        "feedbackObserved": 1000,
        "failed": 3,
        "failedBeforeSending": 2,
        "skipped": 20,
        "bounced": 12,
        "complained": 1,
        "unsubscribed": 6
      },
      "rates": {
        "delivery": 0.98,
        "open": 0.41,
        "click": 0.096,
        "bounce": 0.012,
        "complaint": 0.001,
        "unsubscribe": 0.006
      }
    },
    "push": {
      "current": {
        "sent": 1200,
        "failed": 16,
        "opened": 208,
        "clicked": 72
      },
      "previous": {
        "sent": 900,
        "failed": 12,
        "opened": 156,
        "clicked": 54
      },
      "delta": {
        "sent": 300,
        "failed": 4,
        "opened": 52,
        "clicked": 18
      }
    },
    "conversions": {
      "current": 37,
      "previous": 29,
      "revenue": [
        {
          "currency": "USD",
          "current": 1720.5,
          "previous": 1304
        }
      ],
      "revenueWithheld": false
    },
    "refunds": [
      {
        "currency": "USD",
        "value": 120
      }
    ],
    "refundsWithheld": false,
    "deliverabilityHealth": {
      "band": "healthy",
      "limits": {
        "watch": {
          "bounceRatio": 0.02,
          "complaintRatio": 0.0005
        },
        "critical": {
          "bounceRatio": 0.03,
          "complaintRatio": 0.0008
        }
      },
      "bounceRatio": 0.012,
      "complaintRatio": 0.00025,
      "sampleSize": 4000,
      "minimumSampleSize": 100,
      "feedbackCoverage": 1,
      "minimumFeedbackCoverage": 0.95
    },
    "series": [
      {
        "startsAt": "2026-09-30T23:00:00.000Z",
        "email": {
          "sent": 1000,
          "delivered": 980,
          "opened": 410,
          "openedByMachine": 120,
          "clicked": 96,
          "simulated": 0,
          "feedbackObserved": 1000,
          "failed": 3,
          "failedBeforeSending": 2,
          "skipped": 20,
          "bounced": 12,
          "complained": 1,
          "unsubscribed": 6
        },
        "push": {
          "sent": 300,
          "failed": 4,
          "opened": 52,
          "clicked": 18
        },
        "conversions": 5,
        "revenue": [
          {
            "currency": "USD",
            "value": 412.5
          }
        ]
      },
      {
        "startsAt": "2026-10-01T23:00:00.000Z",
        "email": {
          "sent": 1000,
          "delivered": 980,
          "opened": 410,
          "openedByMachine": 120,
          "clicked": 96,
          "simulated": 0,
          "feedbackObserved": 1000,
          "failed": 3,
          "failedBeforeSending": 2,
          "skipped": 20,
          "bounced": 12,
          "complained": 1,
          "unsubscribed": 6
        },
        "push": {
          "sent": 300,
          "failed": 4,
          "opened": 52,
          "clicked": 18
        },
        "conversions": 0,
        "revenue": []
      }
    ]
  }
}