Reports

Retrieve the performance overview

GET/v1/reports/overview

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

Marketing email send cohorts, not event-occurrence totals, with marketing push in push and on each series row, by the day it was queued. The top-level counts, rates and health are email only; allChannels adds push to the sent, opened and clicked counts. Recent campaign counts are email only; channels says what each campaign targets. Later feedback revises cohorts. Bounce and complaint counts are durable first-occurrence facts, not current statuses. Health bands are local advisory thresholds, not SES account 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.

Query parameters

startDatestringoptional

First day, inclusive, in the workspace timezone. Give with endDate.

date

endDatestringoptional

Last day, inclusive, no later than today. Give with startDate; a window is at most 366 days. Omit both for the last 30 days.

date

Returns

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

generatedAtstringrequired

date-time

timezonestringrequired

The workspace timezone the dates and series days are in.

startDatestringrequired

First day of the window (inclusive).

date

endDatestringrequired

Last day of the window (inclusive).

date

scope"marketing_email"required

What the top-level counts cover.

currentPeriodobjectrequired

The window as UTC instants.

2 child attributes

startstringrequired

Start of the period (inclusive).

date-time

endstringrequired

End of the period (exclusive).

date-time

previousPeriodobjectrequired

The equal-length period just before it.

2 child attributes

startstringrequired

Start of the period (inclusive).

date-time

endstringrequired

End of the period (exclusive).

date-time

currentOverviewCountsrequired

Email counts in the window.

8 child attributes

sentintegerrequired

min -9007199254740991 · max 9007199254740991

deliveredintegerrequired

min -9007199254740991 · max 9007199254740991

openedintegerrequired

min -9007199254740991 · max 9007199254740991

clickedintegerrequired

min -9007199254740991 · max 9007199254740991

feedbackObservedintegerrequired

min -9007199254740991 · max 9007199254740991

bouncedintegerrequired

min -9007199254740991 · max 9007199254740991

complainedintegerrequired

min -9007199254740991 · max 9007199254740991

unsubscribedintegerrequired

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

min -9007199254740991 · max 9007199254740991

previousOverviewCountsrequired

Email counts in the previous period.

8 child attributes

sentintegerrequired

min -9007199254740991 · max 9007199254740991

deliveredintegerrequired

min -9007199254740991 · max 9007199254740991

openedintegerrequired

min -9007199254740991 · max 9007199254740991

clickedintegerrequired

min -9007199254740991 · max 9007199254740991

feedbackObservedintegerrequired

min -9007199254740991 · max 9007199254740991

bouncedintegerrequired

min -9007199254740991 · max 9007199254740991

complainedintegerrequired

min -9007199254740991 · max 9007199254740991

unsubscribedintegerrequired

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

min -9007199254740991 · max 9007199254740991

deltaOverviewCountsrequired

current minus previous.

8 child attributes

sentintegerrequired

min -9007199254740991 · max 9007199254740991

deliveredintegerrequired

min -9007199254740991 · max 9007199254740991

openedintegerrequired

min -9007199254740991 · max 9007199254740991

clickedintegerrequired

min -9007199254740991 · max 9007199254740991

feedbackObservedintegerrequired

min -9007199254740991 · max 9007199254740991

bouncedintegerrequired

min -9007199254740991 · max 9007199254740991

complainedintegerrequired

min -9007199254740991 · max 9007199254740991

unsubscribedintegerrequired

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

min -9007199254740991 · max 9007199254740991

pushobjectrequired

Marketing push counts, by the day it was queued.

3 child attributes

currentobjectrequired

4 child attributes

sentintegerrequired: min -9007199254740991 · max 9007199254740991
failedintegerrequired: min -9007199254740991 · max 9007199254740991
openedintegerrequired: min -9007199254740991 · max 9007199254740991
clickedintegerrequired: min -9007199254740991 · max 9007199254740991

previousobjectrequired

4 child attributes

sentintegerrequired: min -9007199254740991 · max 9007199254740991
failedintegerrequired: min -9007199254740991 · max 9007199254740991
openedintegerrequired: min -9007199254740991 · max 9007199254740991
clickedintegerrequired: min -9007199254740991 · max 9007199254740991

deltaobjectrequired

4 child attributes

sentintegerrequired: min -9007199254740991 · max 9007199254740991
failedintegerrequired: min -9007199254740991 · max 9007199254740991
openedintegerrequired: min -9007199254740991 · max 9007199254740991
clickedintegerrequired: min -9007199254740991 · max 9007199254740991

allChannelsobjectrequired

Marketing email and push together. Push has no delivery receipts, so there is no combined delivered.

3 child attributes

currentobjectrequired

3 child attributes

sentintegerrequired: min -9007199254740991 · max 9007199254740991
openedintegerrequired: min -9007199254740991 · max 9007199254740991
clickedintegerrequired: min -9007199254740991 · max 9007199254740991

previousobjectrequired

3 child attributes

sentintegerrequired: min -9007199254740991 · max 9007199254740991
openedintegerrequired: min -9007199254740991 · max 9007199254740991
clickedintegerrequired: min -9007199254740991 · max 9007199254740991

deltaobjectrequired

3 child attributes

sentintegerrequired: min -9007199254740991 · max 9007199254740991
openedintegerrequired: min -9007199254740991 · max 9007199254740991
clickedintegerrequired: min -9007199254740991 · max 9007199254740991

ratesobjectrequired

Email rates as fractions; 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

deliverabilityHealthobjectrequired

Advisory bounce and complaint health of marketing email.

6 child attributes

bandstringrequired

insufficient_data until the sample and feedback coverage minimums are met.

one of insufficient_data, healthy, watch, critical

limitsobjectrequired

Where the bands start: watch at the line where admins are warned, critical where marketing email pauses.

2 child attributes

watchobjectrequired

2 child attributes

bounceRationumberrequired
complaintRationumberrequired

criticalobjectrequired

2 child attributes

bounceRationumberrequired
complaintRationumberrequired

sampleSizeintegerrequired

Emails the band is judged on.

min 0 · max 9007199254740991

minimumSampleSize100required

feedbackCoveragenumber | nullrequired

Fraction of the sample whose bounce or complaint outcome is known.

min 0

minimumFeedbackCoverage0.95required

seriesobject[]required

One entry per calendar day in the window.

at most 366 items

10 child attributes

sentintegerrequired

min -9007199254740991 · max 9007199254740991

deliveredintegerrequired

min -9007199254740991 · max 9007199254740991

openedintegerrequired

min -9007199254740991 · max 9007199254740991

clickedintegerrequired

min -9007199254740991 · max 9007199254740991

feedbackObservedintegerrequired

min -9007199254740991 · max 9007199254740991

bouncedintegerrequired

min -9007199254740991 · max 9007199254740991

complainedintegerrequired

min -9007199254740991 · max 9007199254740991

unsubscribedintegerrequired

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

min -9007199254740991 · max 9007199254740991

datestringrequired

date

pushobjectrequired

4 child attributes

sentintegerrequired: min -9007199254740991 · max 9007199254740991
failedintegerrequired: min -9007199254740991 · max 9007199254740991
openedintegerrequired: min -9007199254740991 · max 9007199254740991
clickedintegerrequired: min -9007199254740991 · max 9007199254740991

attentionobjectrequired

Things that need a look.

3 child attributes

unverifiedDomainCountintegerrequired

Sending domains not yet verified.

min 0 · max 9007199254740991

staleDraftCountintegerrequired

Drafts untouched for staleAfterDays.

min 0 · max 9007199254740991

staleAfterDays7required

recentCampaignsobjectrequired

2 child attributes

hasMorebooleanrequired

True when more campaigns exist than items lists.

itemsobject[]required

The newest campaigns with their email totals, counted in the background: every few minutes while a send is fresh, less often as it ages, and zeros until first counted.

at most 5 items

11 child attributes

idstringrequired: uuid
namestringrequired
statusstringrequired: one of draft, scheduled, sending, sent, cancelled
channelsstring[]required
createdAtstringrequired: date-time
sentintegerrequired: min 0 · max 9007199254740991
deliveredintegerrequired: min 0 · max 9007199254740991
openedintegerrequired: min 0 · max 9007199254740991
clickedintegerrequired: min 0 · max 9007199254740991
openRatenumber | nullrequired: min 0
clickRatenumber | nullrequired: min 0

conversionsobjectrequired

Goal conversions by when they happened, all channels. 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.

3 child attributes

currentintegerrequired

min 0 · max 9007199254740991

previousintegerrequired

min 0 · max 9007199254740991

revenueobject[]required

Revenue per goal currency.

3 child attributes

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

liveJourneysobjectrequired

2 child attributes

hasMorebooleanrequired

True when more live journeys exist than items lists.

itemsobject[]required

at most 5 items

4 child attributes

idstringrequired: uuid
namestringrequired
triggerEventstringrequired: The event that enrols contacts.
updatedAtstringrequired: date-time

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}`,
  },
});
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']}",
    },
)
data = response.json()["data"]

package main

import (
	"encoding/json"
	"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()

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

Response · 200

{
  "data": {
    "generatedAt": "2030-03-14T09:30:00Z",
    "timezone": "Europe/London",
    "startDate": "2030-03-14",
    "endDate": "2030-03-14",
    "scope": "marketing_email",
    "currentPeriod": {
      "start": "2030-03-14T09:30:00Z",
      "end": "2030-03-14T09:30:00Z"
    },
    "previousPeriod": {
      "start": "2030-03-14T09:30:00Z",
      "end": "2030-03-14T09:30:00Z"
    },
    "current": {
      "sent": -9007199254740991,
      "delivered": -9007199254740991,
      "opened": -9007199254740991,
      "clicked": -9007199254740991,
      "feedbackObserved": -9007199254740991,
      "bounced": -9007199254740991,
      "complained": -9007199254740991,
      "unsubscribed": -9007199254740991
    },
    "previous": {
      "sent": -9007199254740991,
      "delivered": -9007199254740991,
      "opened": -9007199254740991,
      "clicked": -9007199254740991,
      "feedbackObserved": -9007199254740991,
      "bounced": -9007199254740991,
      "complained": -9007199254740991,
      "unsubscribed": -9007199254740991
    },
    "delta": {
      "sent": -9007199254740991,
      "delivered": -9007199254740991,
      "opened": -9007199254740991,
      "clicked": -9007199254740991,
      "feedbackObserved": -9007199254740991,
      "bounced": -9007199254740991,
      "complained": -9007199254740991,
      "unsubscribed": -9007199254740991
    },
    "push": {
      "current": {
        "sent": -9007199254740991,
        "failed": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      },
      "previous": {
        "sent": -9007199254740991,
        "failed": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      },
      "delta": {
        "sent": -9007199254740991,
        "failed": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      }
    },
    "allChannels": {
      "current": {
        "sent": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      },
      "previous": {
        "sent": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      },
      "delta": {
        "sent": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991
      }
    },
    "rates": {
      "delivery": 0,
      "open": 0,
      "click": 0,
      "bounce": 0,
      "complaint": 0,
      "unsubscribe": 0
    },
    "deliverabilityHealth": {
      "band": "insufficient_data",
      "limits": {
        "watch": {
          "bounceRatio": 1,
          "complaintRatio": 1
        },
        "critical": {
          "bounceRatio": 1,
          "complaintRatio": 1
        }
      },
      "sampleSize": 0,
      "minimumSampleSize": 100,
      "feedbackCoverage": 0,
      "minimumFeedbackCoverage": 0.95
    },
    "series": [
      {
        "sent": -9007199254740991,
        "delivered": -9007199254740991,
        "opened": -9007199254740991,
        "clicked": -9007199254740991,
        "feedbackObserved": -9007199254740991,
        "bounced": -9007199254740991,
        "complained": -9007199254740991,
        "unsubscribed": -9007199254740991,
        "date": "2030-03-14",
        "push": {
          "sent": -9007199254740991,
          "failed": -9007199254740991,
          "opened": -9007199254740991,
          "clicked": -9007199254740991
        }
      }
    ],
    "attention": {
      "unverifiedDomainCount": 0,
      "staleDraftCount": 0,
      "staleAfterDays": 7
    },
    "recentCampaigns": {
      "hasMore": true,
      "items": [
        {
          "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
          "name": "Weekend specials",
          "status": "draft",
          "channels": [
            null
          ],
          "createdAt": "2030-03-14T09:30:00Z",
          "sent": 0,
          "delivered": 0,
          "opened": 0,
          "clicked": 0,
          "openRate": 0,
          "clickRate": 0
        }
      ]
    },
    "conversions": {
      "current": 0,
      "previous": 0,
      "revenue": [
        {
          "currency": "USD",
          "current": 1,
          "previous": 1
        }
      ]
    },
    "liveJourneys": {
      "hasMore": true,
      "items": [
        {
          "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
          "name": "Weekend specials",
          "triggerEvent": "triggerEvent_example",
          "updatedAt": "2030-03-14T09:30:00Z"
        }
      ]
    }
  }
}

Example values are generated from the schema.