Skip to content
PayloadPuffin.
Join the waitlist

GET/v1/eventspreview

List accepted events, newest first, with each event’s deliveries rolled up.

Query parameters

  • limit number Optional

    Items to return. Defaults to 100.

    1 to 100

  • cursor string Optional

    Continue before this event ID.

  • status string Optional

    Restrict 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"

  • destinationId string Optional

    Restrict to events with at least one delivery to this destination.

Returns

200

The query result.

  • data object[] Required

    The events on this page, newest first.

    • id string Required

      An event ID, starting with evt_.

    • type string Required

      The event type it was sent with.

    • status string Required

      How 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"

    • unbuiltReason string | null Required

      Why 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.

    • deliveries object Required

      How many deliveries this event fanned out to, and how each ended.

      Show child attributesHide child attributes
      • total number Required

        Deliveries created for this event. Zero when it matched no destination.

      • delivered number Required

        Deliveries the destination accepted.

      • retrying number Required

        Deliveries waiting on a backoff before the next attempt.

      • pending number Required

        Owed but not yet attempted, held because the event arrived too late, or in flight right now.

      • failed number Required

        Deliveries that exhausted their attempts.

      • failure object | null Required

        The most severe failed delivery behind this event. Null when nothing failed, including an event that has not been attempted yet.

    • receivedAt string (date-time) Required

      ISO 8601 timestamp.

    • channels string[] Required

      Channels the event was addressed to, sorted and without duplicates. Empty when it named none, in which case it reached only destinations without channels.

    • sender string Required

      Who 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.

  • links object Required

    Links for navigating a paginated collection.

    • next string | null Required

      URI reference for the next page, or null at the end.

Example

Request
curl -X GET "https://api.payloadpuffin.com/v1/events" \
  -H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY"
Response 200
{
  "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.

  • 4XX application/problem+json

    The request was rejected.