# Messages by delivery status

`GET /api/reporting/v1/messages`  (operationId: `listMessagesByStatus`, group: Reporting)

Outbound messages currently in a status, newest first. status=failed is the delivery-problem report: each row carries the error text recorded at send time. The window defaults to 7 days, up to 90.

Part of the full API, which is included in the Scale plan. Any one of these scopes is enough: `inbox`, `contacts`, `inbox:read`, `contacts:read`. Chat content: messages, names and phone numbers.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | string | yes | Required. The delivery status to list. One of: `sent`, `delivered`, `read`, `failed`, `pending`. |
| `since` | query | string (date-time) | no | Start of the window: an ISO 8601 timestamp or a date (YYYY-MM-DD, start of that UTC day). Default: 7 days ago. Alias: from. |
| `to` | query | string (date-time) | no | End of the window (ISO 8601 or date). Default: now. Alias: until. |
| `phone` | query | string | no | Only this contact. |
| `limit` | query | integer | no | Page size, 1 to 200. Default 50. Default 50. |
| `cursor` | query | string | no | The next_cursor from the previous page. Treat it as opaque. |

**Response 200**: OK (schema `FailedMessageList`)

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[][].id` | integer |  |
| `data[][].message_id` | string, nullable |  |
| `data[][].phone` | string |  |
| `data[][].sent_at` | string (date-time) |  |
| `data[][].sender_type` | string | customer: the contact. bot: the AI agent. agent: a team member (recorded on messages sent from InboxWA). system: any other outbound message (automation, campaign, template, or an older message with no recorded author). A bot reply is never reported as a human. One of: `customer`, `bot`, `agent`, `system`. |
| `data[][].actor` | object, nullable |  |
| `data[][].sender_label` | string, nullable |  |
| `data[][].type` | string, nullable |  |
| `data[][].template_name` | string, nullable |  |
| `data[][].media_url` | string, nullable |  |
| `data[][].status` | string, nullable |  |
| `data[][].source` | string, nullable |  |
| `data[][].error` | string, nullable | Error text recorded at send time. |
| `next_cursor` | string, nullable |  |
| `window` | Window |  |
| `window.from` | string (date-time) | Start of the window. |
| `window.to` | string (date-time) | End of the window. |

Example:

```json
{
  "data": [
    {
      "id": 1102,
      "message_id": "wamid.HBgM...F1",
      "phone": "919876543210",
      "sent_at": "2026-10-02T08:12:00.000Z",
      "sender_type": "system",
      "actor": null,
      "sender_label": null,
      "type": "template",
      "template_name": "renewal_reminder",
      "media_url": null,
      "status": "failed",
      "source": null,
      "error": "#131047 Re-engagement message"
    }
  ],
  "next_cursor": null,
  "window": {
    "from": "2026-09-25T09:30:00.000Z",
    "to": "2026-10-02T09:30:00.000Z"
  }
}
```

**Errors specific to this call.** The common ones (401, 403, 429 and the rest) are in the [Errors guide](https://inboxwa.online/docs/api/guide/errors.md).

| Status | error | When |
| --- | --- | --- |
| 400 | `invalid_status` | status is missing or not recognised. |
| 400 | `window_too_large` | The window is longer than 90 days. |

Part of the InboxWA API reference: https://inboxwa.online/docs/api . Full reference as one document: https://inboxwa.online/docs/api.md . OpenAPI: https://inboxwa.online/openapi.json