List events
GET/v1/eventspreview
List accepted events, newest first, with each event’s deliveries rolled up.
Query parameters
limitnumber OptionalItems to return. Defaults to 100.
1 to 100
cursorstring OptionalContinue before this event ID.
statusstring OptionalRestrict to events whose rolled-up status matches. “failed” matches any event with a failed delivery, even when other destinations succeeded, and never an unbuilt event. “unbuilt” matches the events a source could not build.
Allowed values: "unbuilt", "failed", "retrying", "pending", "delivered", "unmatched"
destinationIdstring OptionalRestrict to events with at least one delivery to this destination.
Returns
The query result.200
dataobject[] RequiredThe events on this page, newest first.
idstring RequiredAn event ID, starting with evt_.
typestring RequiredThe event type it was sent with.
statusstring RequiredHow this event ended, rolled up from its deliveries. “unbuilt” if a source received the request but could not build the event, so it has no deliveries; otherwise “failed” if any delivery failed; otherwise “retrying” if one is backing off; otherwise “pending” if one is still owed and un-attempted, held, or in flight; otherwise “delivered”. An event that matched no destination is “unmatched”.
Allowed values: "unbuilt", "failed", "retrying", "pending", "delivered", "unmatched"
unbuiltReasonstring | null RequiredWhy the source couldn’t build this event, such as the error its transform threw. Present exactly when the event is unbuilt: fix the source’s transform, then rerun the event.
deliveriesobject RequiredHow many deliveries this event fanned out to, and how each ended.
Show child attributesHide child attributes
totalnumber RequiredDeliveries created for this event. Zero when it matched no destination.
deliverednumber RequiredDeliveries the destination accepted.
retryingnumber RequiredDeliveries waiting on a backoff before the next attempt.
pendingnumber RequiredOwed but not yet attempted, held because the event arrived too late, or in flight right now.
failednumber RequiredDeliveries that exhausted their attempts.
failureobject | null RequiredThe most severe failed delivery behind this event. Null when nothing failed, including an event that has not been attempted yet.
receivedAtstring (date-time) RequiredISO 8601 timestamp.
channelsstring[] RequiredChannels the event was addressed to, sorted and without duplicates. Empty when it named none, in which case it reached only destinations without channels.
senderstring RequiredWho sent the event, by ID: the source (src_) whose URL received it, the API key (apk_) that sent it with POST /v1/events, or the user (usr_) who sent it from the console.
linksobject RequiredLinks for navigating a paginated collection.
nextstring | null RequiredURI reference for the next page, or null at the end.
Example
curl -X GET "https://api.payloadpuffin.com/v1/events" \
-H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY"{
"data": [
{
"id": "id",
"type": "type",
"status": "unbuilt",
"unbuiltReason": "unbuiltReason",
"deliveries": {
"total": 0,
"delivered": 0,
"retrying": 0,
"pending": 0,
"failed": 0,
"failure": {
"destinationId": "destinationId",
"attemptNumber": 1,
"at": "at"
}
},
"receivedAt": "receivedAt",
"channels": [
"channels"
],
"sender": "sender"
}
],
"links": {
"next": "next"
}
}Errors
Errors use application/problem+json. The code member is stable; branch on it rather than on title or detail.
4XXapplication/problem+jsonThe request was rejected.