Skip to content
PayloadPuffin.
Join the waitlist

Get an analytics series

GET/v1/analytics/seriespreview

Get counters per step over a range, one series for the key of a dimension. A read that is too large is refused with 400 validation_failed, never cut short: one that spans more than 400 steps, or covers too much detail. Narrow the range or use a coarser step.

Query parameters

  • dimension string Required

    What a series is keyed by: app (one series for the whole app), event_type, destination, or latency (a latency histogram of one destination or of the whole app).

    Allowed values: "app", "event_type", "destination", "latency"

  • step string Required

    The width of one point: hour, day, week (starting Monday), month or year, in UTC.

    Allowed values: "hour", "day", "week", "month", "year"

  • from string (date-time) Required

    The inclusive start of the range, aligned to the step in UTC.

  • to string (date-time) Required

    The exclusive end of the range, aligned to the step in UTC.

  • key string Optional

    One destination ID or event type. Required for every dimension except app, which is refused a key. For the latency dimension ‘’ is the app-wide row.

  • metric string Optional

    Required for the latency dimension, and refused for the others. attempt is one HTTP request to a destination. queue spans event accepted to first attempt started, delivery spans event accepted to first success, and terminal spans event accepted to success or the last failed attempt.

    Allowed values: "attempt", "queue", "delivery", "terminal"

Returns

200

The query result.

  • data object Required

    One series per key, each with one point per step.

    • dimension string Required

      What a series is keyed by: app (one series for the whole app), event_type, destination, or latency (a latency histogram of one destination or of the whole app).

      Allowed values: "app", "event_type", "destination", "latency"

    • step string Required

      The width of one point: hour, day, week (starting Monday), month or year, in UTC.

      Allowed values: "hour", "day", "week", "month", "year"

    • from string (date-time) Required

      The inclusive start of the range.

    • to string (date-time) Required

      The exclusive end of the range.

    • series object[] Required

      One series per key, sorted by key. The app dimension has one series with a null key.

      Show child attributesHide child attributes
      • key string | null Required

        The destination ID or event type the row belongs to. Null for the app dimension. ‘’ for the app-wide latency row, and ‘pp/other’ for the event types past the monthly cap, which are counted together. Event types starting with ‘pp/’ are reserved.

      • points object[] Required

        One point per step from from to to, oldest first, with empty steps filled with 0.

        Show child attributesHide child attributes
        • at string (date-time) Required

          The start of the step.

        • values object Required

          Counters summed into the step, by name. App and destination values carry attempts, delivered, failed and retried, and destination values also carry status classes and latency extremes in milliseconds. unhealthy counts attempts that say the endpoint is failing (a network error, a 3xx, a 5xx, a 4xx other than 400, 413, 422 and 429), and ignored counts attempts that say nothing about it: a payload rejection (400, 413, 422), a 429, and a failed or delivered attempt numbered 3 or more of one delivery. Latency values carry p50, p95 and p99 in milliseconds and the sample count. A counter with nothing recorded is 0.

Example

Request
curl -X GET "https://api.payloadpuffin.com/v1/analytics/series?dimension=app&step=hour&from=2026-10-21T00%3A00%3A00.000Z&to=2026-10-22T00%3A00%3A00.000Z" \
  -H "Authorization: Bearer $PAYLOADPUFFIN_API_KEY"
Response 200
{
  "data": {
    "dimension": "app",
    "step": "hour",
    "from": "from",
    "to": "to",
    "series": [
      {
        "key": "key",
        "points": [
          {
            "at": "at",
            "values": {}
          }
        ]
      }
    ]
  }
}

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.