Selecting a report

By default, the endpoint returns the newest report of the configuration. To request a different one, pass one of the following parameters, but not both:

• generated_on returns the newest report generated on that day, in the YYYY-MM-DD format. For example, generated_on=2026-09-15.
• report_id returns one specific report, using the report_id from an earlier response or the X-Xeneta-Report-Id header.

📘

Generation day is in UTC

generated_on refers to the day the report was generated, in UTC, not to the period its data covers. A report generated at 23:59 UTC on 15 September 2026 belongs to 2026-09-15, whatever your local time zone. If several reports were generated on the same day, the newest one is returned. To get an earlier one, use its report_id.

If no report was generated on the requested day, the endpoint returns 404 with the code no_report_on_date. It never falls back to an earlier day.

The endpoint ignores any parameters it does not recognize.

Configurations with several datasets

An ocean configuration that exports several datasets produces several files per run. The endpoint cannot return those yet, and responds with 409 and the code multiple_files_per_run. To download that data through the API, set up one configuration per dataset.

Error responses

Every error response from this endpoint carries a code that does not change, so your integration can rely on it:

{
  "detail": {
    "code": "invalid_parameter",
    "parameter": "generated_on"
  }
}

The only exceptions are server errors and a missing or unknown API key. A request without a valid API key is rejected before it reaches Datalink, with 403 and the body {"message": "Forbidden"}.

Response codes

In addition to the standard response codes, this endpoint behaves as follows.

🚧

Retrying server errors

502 - Bad Gateway, 503 - Service Unavailable and 504 - Gateway Timeout are temporary, so retry them after an increasing delay. Any other unexpected error returns 500 - Internal Server Error.

Examples

Each example below calls the endpoint, reads url from the response and downloads the file. The -f option makes curl stop when the endpoint returns an error, instead of trying to download a link that is not there. Name the file after the format in the response, since air reports are ZIP archives.

Newest report

url=$(curl -fsS -H "X-Auth: $XENETA_API_KEY" \
  "https://api.xeneta.com/v3.0/datalink/report?configuration_id=xArk" | jq -er .url) &&
  curl -fsS -o latest.csv "$url"

Report generated on a given day

url=$(curl -fsS -H "X-Auth: $XENETA_API_KEY" \
  "https://api.xeneta.com/v3.0/datalink/report?configuration_id=xArk&generated_on=2026-09-15" | jq -er .url) &&
  curl -fsS -o report-2026-09-15.csv "$url"

One specific report

url=$(curl -fsS -H "X-Auth: $XENETA_API_KEY" \
  "https://api.xeneta.com/v3.0/datalink/report?configuration_id=xArk&report_id=U4nnv" | jq -er .url) &&
  curl -fsS -o report-U4nnv.csv "$url"