> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primefreight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a tracking request

> Retrieve details of a specific tracking request

# Get a tracking request

Retrieve the details of a specific tracking request by its ID. This endpoint returns the current status of the tracking request and includes the associated shipment data if the tracking request was successful.

## Endpoint Overview

**GET** `/tracking_requests/{id}`

This endpoint retrieves tracking request details and associated shipment information.

## Request Format

### Headers

| Header      | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `X-API-Key` | string | Yes      | Your API key for authentication |

### Path Parameters

| Parameter | Type   | Required | Description                                   |
| --------- | ------ | -------- | --------------------------------------------- |
| `id`      | string | Yes      | The unique identifier of the tracking request |

## Response Format

### Success Response (200 OK)

```json theme={null}
{
  "data": {
    "id": "ba4cb904-827f-4038-8e31-1e92b3356218",
    "type": "tracking_request",
    "attributes": {
      "request_number": "MEDUFR030802",
      "request_type": "bill_of_lading",
      "scac": "MSCU",
      "ref_numbers": [],
      "created_at": "2020-04-04T16:13:35-07:00",
      "updated_at": "2020-04-04T17:13:35-07:00",
      "status": "created",
      "failed_reason": null
    },
    "relationships": {
      "tracked_object": {
        "data": {
          "id": "eb6f218a-0b4a-47f9-8ef9-759aa5e0ea83",
          "type": "shipment"
        }
      }
    },
    "links": {
      "self": "/v2/tracking_requests/ba4cb904-827f-4038-8e31-1e92b3356218"
    }
  },
  "included": [
    {
      "id": "eb6f218a-0b4a-47f9-8ef9-759aa5e0ea83",
      "type": "shipment",
      "attributes": {
        "created_at": "2020-04-04T16:13:37-07:00",
        "bill_of_lading_number": "MEDUFR030802",
        "ref_numbers": [],
        "shipping_line_scac": "MSCU",
        "shipping_line_name": "Mediterranean Shipping Company",
        "port_of_lading_locode": "FRFOS",
        "port_of_lading_name": "Fos-Sur-Mer",
        "port_of_discharge_locode": "USOAK",
        "port_of_discharge_name": "Oakland",
        "pod_vessel_name": "MSC ALGECIRAS",
        "pod_vessel_imo": "9605243",
        "pod_voyage_number": "920A",
        "destination_locode": "USOAK",
        "destination_name": "Oakland",
        "destination_timezone": "America/Los_Angeles",
        "destination_ata_at": "2019-06-21T18:46:00-07:00",
        "destination_eta_at": null,
        "pol_etd_at": null,
        "pol_atd_at": "2019-05-24T03:00:00-07:00",
        "pol_timezone": "Europe/Paris",
        "pod_eta_at": null,
        "pod_ata_at": "2019-06-21T18:46:00-07:00",
        "pod_timezone": "America/Los_Angeles"
      },
      "relationships": {
        "port_of_lading": {
          "data": {
            "id": "6d8c6c29-72a6-49ad-87b7-fd045f202212",
            "type": "port"
          }
        },
        "port_of_discharge": {
          "data": {
            "id": "42d1ba3a-f4b8-431d-a6fe-49fd748a59e7",
            "type": "port"
          }
        },
        "pod_terminal": {
          "data": null
        },
        "destination": {
          "data": {
            "id": "42d1ba3a-f4b8-431d-a6fe-49fd748a59e7",
            "type": "port"
          }
        },
        "containers": {
          "data": [
            {
              "id": "11c1fa10-52a5-48e2-82f4-5523756b3d0f",
              "type": "container"
            }
          ]
        }
      },
      "links": {
        "self": "/v2/shipments/eb6f218a-0b4a-47f9-8ef9-759aa5e0ea83"
      }
    }
  ]
}
```

### Response Fields

| Field                                    | Type   | Description                                               |
| ---------------------------------------- | ------ | --------------------------------------------------------- |
| `data.id`                                | string | Unique identifier for the tracking request                |
| `data.type`                              | string | Resource type (always "tracking\_request")                |
| `data.attributes.request_type`           | string | Type of tracking request                                  |
| `data.attributes.request_number`         | string | The tracking number being monitored                       |
| `data.attributes.shipping_line_scac`     | string | The SCAC code of the shipping line                        |
| `data.attributes.ref_numbers`            | array  | Array of reference numbers                                |
| `data.attributes.shipment_tags`          | array  | Array of tags                                             |
| `data.attributes.created_at`             | string | ISO 8601 timestamp when created                           |
| `data.attributes.updated_at`             | string | ISO 8601 timestamp when last updated                      |
| `data.attributes.status`                 | string | Current status ("pending", "created", "failed")           |
| `data.attributes.failed_reason`          | string | Reason for failure if failed, null otherwise              |
| `data.relationships.tracked_object.data` | object | The tracked shipment object if successful, null otherwise |
| `data.links.self`                        | string | URL to retrieve this tracking request                     |
| `included`                               | array  | Array of included related resources (shipments)           |

## Status Codes

| Code | Description                             |
| ---- | --------------------------------------- |
| 200  | Tracking request retrieved successfully |
| 404  | Tracking request not found              |
| 401  | Authentication failed - invalid API key |
| 429  | Rate limit exceeded                     |

## Tracking Request Statuses

The tracking request can have the following statuses:

* **pending**: The tracking request has been created and the system is attempting to fetch shipment data
* **created**: The tracking request was successful and a shipment object has been created
* **failed**: The tracking request failed to fetch shipment data

## Error Responses

### Not Found Error (404)

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Tracking request not found",
    "type": "not_found_error"
  }
}
```

### Authentication Error (401)

```json theme={null}
{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}
```