# List Inbox Pieces > `GET /inboxes/{inbox_id}/pieces` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listinboxpieces/ URL: `GET https://api.earthclassmail.com/v1/inboxes/{inbox_id}/pieces` Lists the pieces in an inbox. Supports sorting, filtering, and paging. ## Filters The `filters` query parameter accepts a comma-separated list of `key:value` pairs that narrow results. Allowed filter keys: `in`, `to`, `from`, `received_after`, `received_before`, `at`, `carrier`, `class`, `contains`. - **received_after** / **received_before** — Filter by received date. Value must be a valid UTC datetime. - **to** — Filter by recipient name (prefix match). - **from** — Filter by sender name (prefix match). - **in** — Filter by location. Use `all_items` to include all. - **carrier** / **class** — Filter by shipping carrier and service class. When `class` is provided, `carrier` must also be provided. - **contains** — Search within piece content. - **at** — Filter by facility location. Multiple filters can be combined in a single `filters` value. ### Examples Retrieve pieces received after a specific date: ``` ?filters=received_after:2024-01-15T00:00:00Z ``` Retrieve pieces addressed to a specific recipient: ``` ?filters=to:John Smith ``` ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 95, which is also the maximum. Larger values return 95 items per page. | | `sort_by` | query | no | string | The field to sort the result set by. Allowed values: id, received_at, sender.name, recipient.name. Defaults to id. | | `sort_direction` | query | no | integer | The direction to sort the result set by. 0 for ascending, 1 for descending. Defaults to ascending (0). | | `recipient_ids` | query | no | string | Only return pieces assigned to the given recipients. Comma-separated list of recipient IDs. | | `folder_id` | query | no | string | Only return pieces in the given folder. | | `attributes` | query | no | string | Only return pieces that have the given attributes. Allowed values: archived, trashed, payment-detected, pending, scanned, shipped, stored, unscanned. | | `filters` | query | no | string | Additional filter parameters as comma-separated key:value pairs. Allowed keys: in, to, from, received_after, received_before, at, carrier, class, contains. | | `payload_type` | query | no | integer | Specifies the payload components to return. This is a flags parameter — values can be combined by addition. 0: All, 1: Piece data only, 2: Count only, 4: Media only. Defaults to 0. | | `tag_id` | query | no | string | Limits results to items with the specified tags. Comma-separated list of tag IDs. Possible values are provided by the listInboxTags operation. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `Piece`) Example: ```json { "current_page": 1, "data": [ { "created_at": "2018-07-23T21:25:52Z", "id": 14460059, "updated_at": "2018-07-23T21:25:52Z", "attributes": [ "unscanned", "read", "inbox", "stored" ], "barcode": "0000000101 0016615290", "carrier": { "class": "Unknown", "name": "Unknown" }, "depth_in_inches": 0.1, "end_user_operation_status": null, "height_in_inches": 3.9, "inbox_id": 97599, "insights": [], "length_in_inches": 8.88, "license_plate": 433808312186, "mailbox_folder_id": 0, "media": [ { "content_type": "image/jpg", "id": "1_1_2_0_3", "tags": [ "color", "medium", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2018-09-12T20:46:01Z", "page_count": 1, "piece_id": 14460059 } ], "operation_action": null, "page_count_actual": null, "page_count_estimate": 2, "piece_sub_type": "letter", "piece_type": "mail", "received_at": "2018-07-23T21:25:52Z", "recipient": { "id": 122028, "inbox_id": 97599, "name": "Bruce Wayne" }, "sender": null, "tags": [ "unscanned", "read", "inbox", "stored" ], "user_defined_tags": [], "weight_in_ounces": 0.16 } ], "from": 1, "last_page": 15, "per_page": 1, "to": 1, "total": 15 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null)