---
title: "List Faxes"
method: GET
path: "/fax"
tags: ["faxes"]
---

# List Faxes

`GET /fax`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/fax`
- Auth: API key in header `PINNACLE-API-KEY`

List your team's fax history, newest first.

**HIPAA only:** this endpoint exists only in Pinnacle's HIPAA cell and is unavailable at `https://api.pinnacle.sh`.

Results contain complete faxes only. Use `nextOffset` until it is null. The maximum page size is 100 records and the maximum offset is 100,000.

## Query parameters

- `limit` integer
- `offset` integer
- `direction` 'INBOUND' | 'OUTBOUND': `OUTBOUND` for faxes sent by your team or `INBOUND` for faxes received by your team.

## Response `200`

Fax history.

- FaxList
  - `data` Fax[], required
    - `id` string, uuid, required
    - `direction` 'INBOUND' | 'OUTBOUND', required: `OUTBOUND` for faxes sent by your team or `INBOUND` for faxes received by your team.
    - `from` string, required: Sender number in E.164 format.
    - `to` string, required: Recipient number in E.164 format.
    - `status` 'PREPARING' | 'SUBMITTING' | 'SUBMISSION_UNKNOWN' | 'QUEUED' | 'PROCESSING' | 'SENDING' | 'RECEIVING' | 'DELIVERED' | 'RECEIVED' | 'FAILED' | 'CANCELLED', required: Current state of the fax: - `PREPARING`: Pinnacle is downloading, validating, converting, splitting, or archiving the document. - `SUBMITTING`: The fax is waiting for transmission to start. - `SUBMISSION_UNKNOWN`: Transmission may have started, but Pinnacle cannot confirm it. The fax is not retried automatically. - `QUEUED`: The outbound fax is queued for transmission. - `PROCESSING`: The outbound document is being processed. - `SENDING`: The outbound fax is being transmitted. - `RECEIVING`: An inbound fax is in progress. - `DELIVERED`: Every outbound part was delivered. - `RECEIVED`: The inbound fax was received and archived. - `FAILED`: Preparation, submission, or delivery failed. `partialContent` indicates whether any pages were transmitted. - `CANCELLED`: The outbound fax was cancelled before transmission started.
    - `pages` integer, required: Transmitted page count across the fax. This can be zero before transmission and can include only transmitted pages after a partial failure. Outbound documents can contain at most 3,500 pages.
    - `durationSeconds` number, double, required: Total transmission duration in seconds.
    - `partialContent` boolean, required: Whether only part of the document was delivered, including when an earlier part succeeded before a later part failed.
    - `failureReason` 'MEDIA_PREPARATION_FAILED' | 'MEDIA_PREPARATION_INTERRUPTED' | 'INSUFFICIENT_CREDITS' | 'SUBMISSION_UNCONFIRMED' | 'SUBMISSION_REJECTED' | 'DELIVERY_FAILED', required: Stable failure category, or null when no failure is recorded: - `MEDIA_PREPARATION_FAILED`: The source was unavailable, invalid, unsupported, over a limit, or could not be rendered. - `MEDIA_PREPARATION_INTERRUPTED`: Preparation could not be completed after retries. - `INSUFFICIENT_CREDITS`: The team's available credits could not cover the prepared page count. - `SUBMISSION_UNCONFIRMED`: Transmission may have started, so Pinnacle will not retry automatically. - `SUBMISSION_REJECTED`: Transmission could not start. - `DELIVERY_FAILED`: Delivery failed or a transmitted part did not match the expected page count.
    - `cost` number, double, required: Settled fax cost in USD, calculated at $0.025 per final transmitted page. Quality does not change the rate.
    - `reservedCost` number, double, required: Credit reserved after document preparation for an unsettled outbound fax, in USD. This equals $0.025 multiplied by the prepared page count, regardless of quality, and is zero while status is `PREPARING`.
    - `billingStatus` 'PENDING' | 'SETTLED', required: Billing state for the fax.
    - `hasMedia` boolean, required: Whether Pinnacle has archived the fax document.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `nextOffset` integer, nullable, required: Offset for the next page, or null when no more records exist.

## Other responses

- `400`: The request was unacceptable, often due to providing an invalid update. <br> Errors may originate from invalid payload or from Pinnacle's additional validation checks. For example, providing an URL that cannot be accessed, updating a campaign that is currently being reviewed, updating data that you cannot access, sending a malformed message, and so on. <br> For `Pinnacle Validation Error` inspect the `error` payload to determine the source of the failure. These errors are likely due to additional validation and business logic checks.<br> For `Request Validation Error` inspect the `description` and `errors` payload to determine the source of failure. These errors are likely due to invalid payload inside the request.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.
- `503`: Fax support is disabled or temporarily unavailable in this deployment.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)