Skip to content
PayloadPuffin.
Join the waitlist

Analytics

To find which receivers are failing or slowing down, compare the delivery outcomes and latency for each destination. PayloadPuffin counts what happens in each app: accepted events, deliveries, attempts and their outcomes, plus latency. The console's Analytics and Overview pages show these numbers. The API returns the same numbers to an API key with the analytics:read scope.

Find destinations with failed deliveries

This Node.js example reads the last 24 complete UTC hours. Use an API key with analytics:read:

JavaScript
const to = new Date();
to.setUTCMinutes(0, 0, 0);
const from = new Date(to.getTime() - 24 * 60 * 60 * 1000);
const url = new URL('https://api.payloadpuffin.com/v1/analytics/totals');
url.search = new URLSearchParams({
	dimension: 'destination',
	from: from.toISOString(),
	to: to.toISOString(),
});
const response = await fetch(url, {
	headers: { Authorization: `Bearer ${process.env.PAYLOADPUFFIN_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const { rows } = await response.json();
for (const row of rows) {
	console.log(row.name ?? row.key, row.values.failed, row.values.attempts);
}

Each row identifies one destination. failed counts deliveries that reached a final failure during the range. attempts counts HTTP requests, including retries. A failed attempt that will retry doesn't increase failed yet. The range counts activity when it happens, so an event accepted earlier can contribute attempts during this range.

Counts and billing usage

Event, delivery and attempt counts measure different things. One event can create several deliveries, and each delivery can make several attempts. They aren't billable units; see Plans and billing for that calculation.

Get usage returns this app's unitsThisMonth, the organization's shared unitQuota, and its quotaExceeded state. It doesn't return total usage across the organization. The console's billing page and sidebar meter show that organization-wide total. The response also includes lifetime counters such as eventsReceived, deliveriesCreated and attempts; those aren't monthly usage figures.

Operations

OperationReturns
Get usageApp billable units this month, organization quota state, and app lifetime counters
Get latency percentilesThe p50, p95 and p99 of one latency metric over the last 24 hours
Get an analytics seriesCounters per step over a range, one series per key
Get analytics totalsCounters summed over a range, one row per key

Dimensions

A series or a totals read groups its counters by one dimension.

dimensionOne series or row per
appApp. There is one, with a null key.
event_typeEvent type
destinationDestination ID
latencyDestination ID, or '' for the whole app. Series reads only.

A totals row for a destination also carries its name. A deleted destination keeps the last name it had, and deleted is true.

Latency metrics

metricMeasures
attemptOne HTTP request to a destination
queueFrom event accepted to the first attempt started
deliveryFrom event accepted to the first successful attempt
terminalFrom event accepted to success or the last failure

Percentiles are estimates. PayloadPuffin counts each measurement in a histogram bucket, and a percentile is the upper bound of the bucket that holds it.

Ranges

A series read takes a step of hour, day, week, month or year, in UTC. A week starts on Monday. from and to must fall on a step boundary, and to is exclusive. A totals read takes from and to on whole UTC hours.

Hour and day detail is kept for a limited time; app counters and monthly detail are kept for the life of the app. A range that needs detail older than that is refused, and detail says from when it's kept. Use a coarser step or a later from.

Limits

A read never returns part of a range. When a read is too large, it fails with 400 validation_failed, and detail says what to change: a series that spans more than 400 steps, totals over more than 1,000 keys, or a range with too much detail to read at once. To fit a read, narrow the range, pick one key, or use a coarser step.