---
title: "Download tracking events (milestones) as one flat table"
method: GET
path: "/feed/events"
tags: ["BI feeds"]
---

# Download tracking events (milestones) as one flat table

`GET /feed/events`

## Request

- Base URL: `https://trackberry.com/api/v1`
- URL: `https://trackberry.com/api/v1/feed/events`
- Auth: HTTP bearer

Use this to analyze milestones across shipments: dwell time between discharge and gate out, port-to-port legs, on-time rates by event. One row per tracking event, with its shipment id and reference so it joins to the shipments feed. Only the last 90 days of events by default; pass `from` for more. Not paged: streamed in one response. Append `.csv` or `.json`.

## Query parameters

- `from` string
- `to` string

## Headers

- `Trackberry-Version` string

## Response `200`

The whole table. Append `.csv` to the path for CSV, `.json` or nothing for JSON.

- object
  - `object` 'feed', required: Always `feed`.
  - `name` 'events', required: Which feed this is.
  - `columns` string[], required: The column names, in order. Stable across requests.
  - `data` EventFeedRow[], required: One flat object per row, keyed by the column names.
    - `id` string, required: The event id.
    - `shipment_id` string, required: The shipment the event belongs to. Join to the shipments feed on `id`.
    - `shipment_reference` string, required: That shipment's Trackberry reference.
    - `container_number` string, nullable, required: The container the event is about. Null for events on the whole shipment, and for air.
    - `milestone` string, required: What happened, for example `loaded`, `departed`, `arrived`, `discharged`, `gate_out`, `empty_return`. New milestones may be added.
    - `actual` boolean, required: True when it happened, false when it is an estimate.
    - `occurred_at` string, date-time, nullable, required: When it happened or is expected, in UTC.
    - `location_name` string, nullable, required: Where it happened, as the carrier names the place.
    - `location_code` string, nullable, required: The UN/LOCODE or airport code of the place, when known.
    - `location_country_code` string, nullable, required: The two-letter country code of the place.
    - `vessel_name` string, nullable, required: The vessel involved, for ocean events.
    - `vessel_imo` string, nullable, required: The vessel's IMO number.
    - `voyage` string, nullable, required: The voyage number.
    - `flight_number` string, nullable, required: The flight number, for air events.
    - `latitude` number, nullable, required: Latitude of the event, when the carrier gave a position.
    - `longitude` number, nullable, required: Longitude of the event, when the carrier gave a position.

## 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)