---
title: "Get Fax"
method: GET
path: "/fax/{id}"
tags: ["faxes"]
---

# Get Fax

`GET /fax/{id}`

## Request

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

Retrieve a fax and a one-hour signed document URL when its media is available.

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

Only faxes owned by your team are accessible. Unknown IDs and records removed by your team's HIPAA retention policy return 404. `mediaUrl` is null until archival completes and expires one hour after retrieval; request the fax again for a new URL.

## Path parameters

- `id` string, uuid, required

## Response `200`

Fax details.

- FaxDetail
  - `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
  - `mediaUrl` string, uri, nullable, required: One-hour signed URL for the archived document, or null until media is available. Treat the URL as sensitive because anyone who possesses it can access the document until it expires; request this endpoint again for a fresh URL.

## 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.
- `404`: The requested resource could not be found. <br> This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.
- `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)