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:
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
| Operation | Returns |
|---|---|
| Get usage | App billable units this month, organization quota state, and app lifetime counters |
| Get latency percentiles | The p50, p95 and p99 of one latency metric over the last 24 hours |
| Get an analytics series | Counters per step over a range, one series per key |
| Get analytics totals | Counters summed over a range, one row per key |
Dimensions
A series or a totals read groups its counters by one dimension.
dimension | One series or row per |
|---|---|
app | App. There is one, with a null key. |
event_type | Event type |
destination | Destination ID |
latency | Destination 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
metric | Measures |
|---|---|
attempt | One HTTP request to a destination |
queue | From event accepted to the first attempt started |
delivery | From event accepted to the first successful attempt |
terminal | From 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.