---
title: "List shipments whose demurrage free time is nearly or already used up"
method: GET
path: "/free_time/at_risk"
tags: ["Free time"]
---

# List shipments whose demurrage free time is nearly or already used up

`GET /free_time/at_risk`

## Request

- Base URL: `https://trackberry.com/api/v1`
- URL: `https://trackberry.com/api/v1/free_time/at_risk`
- Auth: HTTP bearer

Use this for a daily "what do I need to collect today" view. Returns one free-time summary per shipment that has a demurrage clock running with 2 days or fewer left (or already overdue), most urgent first. Only ocean shipments that are not archived, not yet received into the warehouse, and were discharged in the last 45 days are considered. Not paged. Shipments with unknown free-time terms never appear here; `terms_unknown` on `get_shipment_free_time` says when terms are missing.

## Headers

- `Trackberry-Version` string

## Response `200`

The at-risk shipments, most urgent first.

- object: The envelope every list endpoint returns.
  - `object` 'list', required: Always `list`.
  - `data` object[], required: The items of this page, in the order the endpoint documents. Each item is an object of the kind the endpoint returns.
    - `object` 'free_time_summary', required: Always `free_time_summary`.
    - `shipment_id` string, required: The shipment id.
    - `shipment_reference` string, required: The shipment's Trackberry reference.
    - `transport_reference` string, nullable, required: The shipment's bill of lading, air waybill or container number.
    - `at_risk` boolean, required: True when the demurrage clock is running with known free days and 2 days or fewer are left (or it is already overdue). Shipments with unknown terms are never at risk.
    - `terms_unknown` boolean, required: True when the free days for demurrage or detention are not known, meaning neither the shipment, an arrival notice nor the organization's carrier terms supply them. Set the terms in Trackberry to get countdowns.
    - `demurrage` FreeTimeClock[], required: One demurrage clock per container. Empty for shipments that are not ocean or have no tracking events for it.
      - `object` 'free_time_clock', required: Always `free_time_clock`.
      - `kind` 'demurrage' | 'detention', required: Which charge this clock measures.
      - `container_number` string, nullable, required: The container the clock is for. Null when tracking events carry no container number.
      - `state` 'not_started' | 'running' | 'running_unknown_terms' | 'stopped' | 'end_not_reported' | 'return_not_reported', required: `not_started` means the clock has nothing to count from yet; `running` means it is counting against known free days; `running_unknown_terms` means it is counting but the free days are unknown (only `elapsed_days` is filled); `stopped` means it has ended (see `ended_on`, `used_days`, `overdue_days`); `end_not_reported` (demurrage) and `return_not_reported` (detention) mean the clock gave up waiting for the ending event because the container was archived or received in the warehouse, or 30 days passed without it.
      - `free_days` integer, nullable, required: The number of free days that apply. Null when unknown.
      - `free_days_source` 'shipment' | 'notice' | 'carrier' | 'null', nullable, required: Where `free_days` comes from, in order of authority. `shipment` means set on the shipment itself; `notice` means read from the latest arrival notice; `carrier` means the organization's negotiated terms for this carrier. Null when `free_days` is unknown.
      - `free_days_basis` 'calendar' | 'working' | 'null', nullable, required: How days are counted. `calendar` counts every day; `working` skips weekends and the country's public holidays. Null when there are no known terms.
      - `started_on` string, date, nullable, required: The port-local day the clock started (the discharge day for demurrage, the gate-out day for detention). Null while `not_started`.
      - `ended_on` string, date, nullable, required: The port-local day the clock ended. Null unless `stopped`.
      - `last_free_day` string, date, nullable, required: The last day that is still free. Null unless `running`.
      - `days_left` integer, nullable, required: Free days remaining after today, counted on `free_days_basis`. 0 means today is the last free day. Negative once overdue (at least -1). Null unless `running`.
      - `elapsed_days` integer, nullable, required: Calendar days since the start, counting the start day. Only set while `running_unknown_terms`.
      - `used_days` integer, nullable, required: How many days were used between start and end, counting both. Only set when `stopped`.
      - `overdue_days` integer, nullable, required: How many days beyond the free days were used. 0 when the clock stopped in time. Only set when `stopped` and the free days are known.
      - `carrier` string, nullable, required: The carrier the terms belong to, as a label.
    - `detention` FreeTimeClock[], required: One detention clock per container, in the same order as `demurrage`. Empty for shipments that are not ocean.
      - `object` 'free_time_clock', required: Always `free_time_clock`.
      - `kind` 'demurrage' | 'detention', required: Which charge this clock measures.
      - `container_number` string, nullable, required: The container the clock is for. Null when tracking events carry no container number.
      - `state` 'not_started' | 'running' | 'running_unknown_terms' | 'stopped' | 'end_not_reported' | 'return_not_reported', required: `not_started` means the clock has nothing to count from yet; `running` means it is counting against known free days; `running_unknown_terms` means it is counting but the free days are unknown (only `elapsed_days` is filled); `stopped` means it has ended (see `ended_on`, `used_days`, `overdue_days`); `end_not_reported` (demurrage) and `return_not_reported` (detention) mean the clock gave up waiting for the ending event because the container was archived or received in the warehouse, or 30 days passed without it.
      - `free_days` integer, nullable, required: The number of free days that apply. Null when unknown.
      - `free_days_source` 'shipment' | 'notice' | 'carrier' | 'null', nullable, required: Where `free_days` comes from, in order of authority. `shipment` means set on the shipment itself; `notice` means read from the latest arrival notice; `carrier` means the organization's negotiated terms for this carrier. Null when `free_days` is unknown.
      - `free_days_basis` 'calendar' | 'working' | 'null', nullable, required: How days are counted. `calendar` counts every day; `working` skips weekends and the country's public holidays. Null when there are no known terms.
      - `started_on` string, date, nullable, required: The port-local day the clock started (the discharge day for demurrage, the gate-out day for detention). Null while `not_started`.
      - `ended_on` string, date, nullable, required: The port-local day the clock ended. Null unless `stopped`.
      - `last_free_day` string, date, nullable, required: The last day that is still free. Null unless `running`.
      - `days_left` integer, nullable, required: Free days remaining after today, counted on `free_days_basis`. 0 means today is the last free day. Negative once overdue (at least -1). Null unless `running`.
      - `elapsed_days` integer, nullable, required: Calendar days since the start, counting the start day. Only set while `running_unknown_terms`.
      - `used_days` integer, nullable, required: How many days were used between start and end, counting both. Only set when `stopped`.
      - `overdue_days` integer, nullable, required: How many days beyond the free days were used. 0 when the clock stopped in time. Only set when `stopped` and the free days are known.
      - `carrier` string, nullable, required: The carrier the terms belong to, as a label.
    - `active_clock` FreeTimeClock, required: One demurrage or detention clock for one container. Demurrage starts at the container's discharge and stops at gate out (or, without one, at the return of the empty container). Detention starts at gate out and stops at the return of the empty container. Days are counted in the local calendar of the port. This object has no `id`.
      - `object` 'free_time_clock', required: Always `free_time_clock`.
      - `kind` 'demurrage' | 'detention', required: Which charge this clock measures.
      - `container_number` string, nullable, required: The container the clock is for. Null when tracking events carry no container number.
      - `state` 'not_started' | 'running' | 'running_unknown_terms' | 'stopped' | 'end_not_reported' | 'return_not_reported', required: `not_started` means the clock has nothing to count from yet; `running` means it is counting against known free days; `running_unknown_terms` means it is counting but the free days are unknown (only `elapsed_days` is filled); `stopped` means it has ended (see `ended_on`, `used_days`, `overdue_days`); `end_not_reported` (demurrage) and `return_not_reported` (detention) mean the clock gave up waiting for the ending event because the container was archived or received in the warehouse, or 30 days passed without it.
      - `free_days` integer, nullable, required: The number of free days that apply. Null when unknown.
      - `free_days_source` 'shipment' | 'notice' | 'carrier' | 'null', nullable, required: Where `free_days` comes from, in order of authority. `shipment` means set on the shipment itself; `notice` means read from the latest arrival notice; `carrier` means the organization's negotiated terms for this carrier. Null when `free_days` is unknown.
      - `free_days_basis` 'calendar' | 'working' | 'null', nullable, required: How days are counted. `calendar` counts every day; `working` skips weekends and the country's public holidays. Null when there are no known terms.
      - `started_on` string, date, nullable, required: The port-local day the clock started (the discharge day for demurrage, the gate-out day for detention). Null while `not_started`.
      - `ended_on` string, date, nullable, required: The port-local day the clock ended. Null unless `stopped`.
      - `last_free_day` string, date, nullable, required: The last day that is still free. Null unless `running`.
      - `days_left` integer, nullable, required: Free days remaining after today, counted on `free_days_basis`. 0 means today is the last free day. Negative once overdue (at least -1). Null unless `running`.
      - `elapsed_days` integer, nullable, required: Calendar days since the start, counting the start day. Only set while `running_unknown_terms`.
      - `used_days` integer, nullable, required: How many days were used between start and end, counting both. Only set when `stopped`.
      - `overdue_days` integer, nullable, required: How many days beyond the free days were used. 0 when the clock stopped in time. Only set when `stopped` and the free days are known.
      - `carrier` string, nullable, required: The carrier the terms belong to, as a label.
  - `has_more` boolean, required: True when more items exist after this page. Pass the last item's `id` as `starting_after` to fetch them. Always false for unpaged lists.

## Other responses

- `400`: A parameter or header is invalid (`invalid_parameter`, with `param` naming it), a customer link cannot be made for this shipment (`not_shareable`), an uploaded file is empty, over 50 MB or of a type Trackberry does not read (`file_empty`, `file_too_large`, `unsupported_file_type`), an upload's container number is on more than one live shipment (`ambiguous_container`), an `Idempotency-Key` was already used for a different request (`idempotency_key_reused`) or `Trackberry-Version` names an unpublished version (`invalid_version`, with `param` set to `Trackberry-Version`). A parameter that must be a single value but was sent as an array or hash (`status[]=x`, `q[a]=1`) is also a 400.
- `401`: No token was sent (`missing_token`) or the token is wrong, expired, revoked, or its user left the organization (`invalid_token`). The response has a `WWW-Authenticate` header.
- `403`: The token may not do this. `insufficient_scope`: a write endpoint was called with a read-only token. `read_only_member`: a write endpoint was called by a token whose owner is now a read-only member of the organization. `revoke_not_allowed`: the link can only be revoked by an admin or by the member who made it. `billing_blocked`: an upload needed a new shipment and the organization's billing does not allow one.
- `429`: A rate limit was hit (`rate_limited`). Wait the number of seconds in `Retry-After`. A BI feed answers the same way (`feed_in_progress`) when another feed for the organization is still being produced.

---

[API](https://skmtc.dev/trackberry/apis/trackberry-api.md) · [All operations](https://skmtc.dev/trackberry/apis/trackberry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackberry/apis/trackberry-api/revisions/be06ee7c17f3?raw)