GET/v1/postflows/{id}/stats

Postflow statistics

Counts by status, the next run, the oldest held item, the template version in use and recent items (POSTFLOW-006).

Scope postflows.read

Path parameters

idstringrequired

Returns

8 fields of the 200 answer

postflowIdstringrequired

statusenumrequired

ACTIVEPAUSEDARCHIVED

countsobjectrequired

12 fields

NEEDS_ATTENTIONintegerrequired

SUPPRESSEDintegerrequired

HELDintegerrequired

PENDING_APPROVALintegerrequired

READYintegerrequired

SCHEDULED_FOR_RUNintegerrequired

IN_PRODUCTIONintegerrequired

COMPLETEDintegerrequired

FAILEDintegerrequired

CANCELLEDintegerrequired

RETURNEDintegerrequired

NOT_SENTintegerrequired

scansobjectrequired

2 fields

itemsScannedintegerrequired

scansintegerrequired

nextRunobject or nullrequired

4 fields

runIdstringrequired

cutoffAtdate-timerequired

handoverWeekstringrequired

itemsReadyintegerrequired

oldestHeldobject or nullrequired

3 fields

itemIdstringrequired

createdAtdate-timerequired

ageSecondsintegerrequired

templateVersionobject or nullrequired

2 fields

idstringrequired

numberintegerrequired

recentItemsarray of objectsrequired

29 fields

idstringrequired

statusenumrequired

NEEDS_ATTENTIONSUPPRESSEDHELDPENDING_APPROVALREADYSCHEDULED_FOR_RUNIN_PRODUCTIONCOMPLETEDFAILEDCANCELLEDRETURNEDNOT_SENT

customerStatusenumrequired

NEEDS_ATTENTIONSUPPRESSEDSCHEDULEDIN_PRODUCTIONHANDED_TO_CARRIERCOMPLETEDFAILEDCANCELLEDRETURNEDNOT_SENT

needsAttentionbooleanrequired

warningsarray of objectsrequired

3 fields

codeenumrequired

address_invalidpostal_code_invalidhouse_number_missingcity_missingcountry_not_supporteddestination_not_supportedvariable_missingvariable_type_invalidvariable_too_longimage_fetch_failedimage_resolution_lowtext_overflowexpression_invalidlate_delivery_expectedwaiting_for_fundssuppressedcarrier_codes_missingexcluded_from_run

fieldstringrequired

messagestringrequired

sourceenumrequired

POSTFLOWPOSTBATCHSAMPLE

postflowIdstring or nullrequired

postbatchIdstring or nullrequired

templateVersionIdstring or nullrequired

productobjectrequired

4 fields

idstringrequired

specificationIdstringrequired

finishstringrequired

destinationstringrequired

advertisingCategorystring or nullrequired

isTestbooleanrequired

isSamplebooleanrequired

recipientobject or nullrequired

6 fields

namestringrequired

addressLine1stringrequired

addressLine2string or nullrequired

postalCodestringrequired

citystringrequired

countrystringrequired

variablesobject or nullrequired

sendDatedate or nullrequired

externalIdstring or nullrequired

metadataobject or nullrequired

createdAtdate-timerequired

updatedAtdate-timerequired

readyAtdate-time or nullrequired

scheduledAtdate-time or nullrequired

handedToCarrierAtdate-time or nullrequired

completedAtdate-time or nullrequired

failedAtdate-time or nullrequired

cancelledAtdate-time or nullrequired

anonymisedAtdate-time or nullrequired

qrobject or nullrequired

4 fields

shortUrlstringrequired

scanCountintegerrequired

firstScannedAtdate-time or nullrequired

lastScannedAtdate-time or nullrequired

priceobject or nullrequired

11 fields

idstringrequired

unitPriceCentsintegerrequired

listUnitPriceCentsintegerrequired

currencystringrequired

discountPercentnumber or nullrequired

tierQuantityintegerrequired

tierBasisenumrequired

postbatchrolling30d

basisQuantityintegerrequired

vatTreatmentstringrequired

vatRateintegerrequired

computedAtdate-timerequired

Responses

200Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

404Not found

429Rate limited for this API key and class; wait Retry-After seconds

otherError (RFC 9457 problem details)

Request

curl https://api.postbuddy.nl/v1/postflows/pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K/stats \
  -H "Authorization: Bearer $POSTBUDDY_API_KEY"

import { PostBuddyClient } from '@postbuddy/sdk';

const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! });

const result = await client.postflows.stats('pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K');

import os
from postbuddy import Client

client = Client(os.environ["POSTBUDDY_API_KEY"])

result = client.postflows.stats("pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K")

Response

{
  "postflowId": "pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "status": "ACTIVE",
  "counts": {
    "NEEDS_ATTENTION": 1,
    "SUPPRESSED": 1,
    "HELD": 1,
    "PENDING_APPROVAL": 1,
    "READY": 1,
    "SCHEDULED_FOR_RUN": 1,
    "IN_PRODUCTION": 1,
    "COMPLETED": 1,
    "FAILED": 1,
    "CANCELLED": 1,
    "RETURNED": 1,
    "NOT_SENT": 1
  },
  "scans": {
    "itemsScanned": 1,
    "scans": 1
  },
  "nextRun": {
    "runId": "run_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
    "cutoffAt": "2026-10-16T09:14:02.000Z",
    "handoverWeek": "Example",
    "itemsReady": 1
  },
  "oldestHeld": {
    "itemId": "itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
    "createdAt": "2026-10-16T09:14:02.000Z",
    "ageSeconds": 1
  },
  "templateVersion": {
    "id": "tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
    "number": 1
  },
  "recentItems": [
    {
      "id": "itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
      "status": "HELD",
      "customerStatus": "SCHEDULED",
      "needsAttention": false,
      "warnings": [],
      "source": "POSTFLOW",
      "postflowId": "pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
      "postbatchId": "pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
      "templateVersionId": "tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
      "product": {
        "id": "prd_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
        "specificationId": "psp_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
        "finish": "silk",
        "destination": "Example"
      },
      "advertisingCategory": "Example",
      "isTest": false,
      "isSample": false,
      "recipient": {
        "name": "Sanne de Vries",
        "addressLine1": "Oudegracht 112",
        "addressLine2": "2nd floor",
        "postalCode": "3511 AX",
        "city": "Utrecht",
        "country": "NL"
      },
      "variables": {
        "first_name": "Sanne"
      },
      "sendDate": "2026-11-02",
      "externalId": "crm-0062p00001Xyz",
      "metadata": {
        "crmRecordId": "0062p00001Xyz"
      },
      "createdAt": "2026-10-16T09:14:02.000Z",
      "updatedAt": "2026-10-16T09:14:02.000Z",
      "readyAt": "2026-10-16T09:14:02.000Z",
      "scheduledAt": "2026-10-16T09:14:02.000Z",
      "handedToCarrierAt": "2026-10-16T09:14:02.000Z",
      "completedAt": "2026-10-16T09:14:02.000Z",
      "failedAt": "2026-10-16T09:14:02.000Z",
      "cancelledAt": "2026-10-16T09:14:02.000Z",
      "anonymisedAt": "2026-10-16T09:14:02.000Z",
      "qr": {
        "shortUrl": "https://example.com/r/Fq3ZtR8w",
        "scanCount": 3,
        "firstScannedAt": "2026-10-16T09:14:02.000Z",
        "lastScannedAt": "2026-10-16T09:14:02.000Z"
      },
      "price": {
        "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
        "unitPriceCents": 1250,
        "listUnitPriceCents": 1250,
        "currency": "EUR",
        "discountPercent": 3,
        "tierQuantity": 1,
        "tierBasis": "postbatch",
        "basisQuantity": 1,
        "vatTreatment": "Example",
        "vatRate": 1,
        "computedAt": "2026-10-16T09:14:02.000Z"
      }
    }
  ]
}

{
  "type": "https://docs.postbuddy.nl/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Not found",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K"
}