List Processing Failures

Returns Event recovery rows for a project. Use this endpoint to inspect why a raw event was not fully consumed by the processing pipeline before deciding whether to retry or take follow-up action.

GET /v1/projects/:project_id/usage/unconsumed-events

Authentication

Authorization: Bearer <api-key>

Requires usage read access.

Path Parameters

Field	Required	Description
project_id	Yes	Project that owns logs.

Request Body

Empty. This GET endpoint accepts filters only through query parameters.

Query Parameters

Field	Required	Description
raw_event_id	No	Filter to one source raw event.
subject_type	No	Filter by extracted subject type.
subject_id	No	Filter by extracted subject ID.
reason_code	No	Filter by recovery reason code such as processing_failed.
start_time	No	Start time as Unix seconds, applied to processed_at.
end_time	No	End time as Unix seconds, applied to processed_at.
after_id	No	Cursor ID used for keyset pagination.
limit	No	Page size. Defaults to 100; maximum is 1000.

Example

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/usage/unconsumed-events?reason_code=processing_failed&start_time=1778580000&end_time=1778666400&limit=100' \
  -H 'Authorization: Bearer <api-key>'

Response

{
  "unconsumed_events": [
    {
      "id": "rpl_74c4435a56a9f0ea",
      "raw_event_id": "raw_evt_01",
      "subject_type": "user",
      "subject_id": "user_123",
      "extractor_rule_set_id": "ers_llm_gateway",
      "reason_code": "processing_failed",
      "reason_message": "extractor returned no charge items",
      "processed_at": 1781222400
    }
  ],
  "next_after_id": "rpl_74c4435a56a9f0ea"
}

Notes

• reason_code is a normalized processing-failure reason, not a free-form error string.
• processed_at is the log timestamp used for ordering and time filtering.
• Use List Usage Event Details when you need rated usage rows instead of failure logs.