---
title: "Submit async report job"
method: POST
path: "/api/v0/report"
tags: ["Reports"]
---

# Submit async report job

`POST /api/v0/report`

## Request

- Base URL: `https://api.datalastic.com`
- URL: `https://api.datalastic.com/api/v0/report`
- Auth: one of:
  - API key in header `x-api-key`
  - API key in query parameter `api-key`
- TypeScript: <https://skmtc.dev/datalastic/apis/datalastic-maritime-api/docs/api/v0/report/post.ts> (a function with typed inputs; its response is checked against the schema)

Initiates a bulk data export job. Returns `report_id` immediately with
`status: _PENDING_`. Poll `GET /api/v0/report` until `status` is
`_DONE_`, then download the ZIP from `result_url`.

### Report types

| report_type | Description | Credit cost |
|---|---|---|
| `vessel_list` | Full vessel registry snapshot | 5,000 |
| `port_list` | Full port list snapshot | 500 |
| `request_usage` | Your API key usage log | Free |
| `inradius_history` | Historical AIS for a zone (max 7-day window, max 50 NM radius) | 1 per unique vessel per calendar day, summed across the date range |
| `dry_dock_dates` | Dry dock bulk export | 2,000 |
| `companies` | Maritime companies bulk export | 2,000 |
| `casualty` | Casualties bulk export | 2,000 |
| `inspections` | Inspections bulk export | 2,000 |
| `sales_purchase_demolitions` | Sales and demolitions bulk export | 2,000 |
| `ownership` | Ownership bulk export | 2,000 |
| `class_society` | Classification society bulk export | 2,000 |
| `engine` | Engine data bulk export | 2,000 |

**Credit cost:** the cost of the requested `report_type`, as listed
above. Submitting carries no separate charge on top of that.

You are charged once per report. Checking the status of a report you
already submitted is free, however many times you do it, and that
includes fetching a fresh `result_url` after the previous link expired.
A failed report deducts no credits.

An existing report cannot be restarted. To change the parameters,
submit a new report, which is charged as a new report.

## Request body

- object
  - `report_type` 'vessel_list' | 'port_list' | 'request_usage' | 'inradius_history' | 'dry_dock_dates' | 'companies' | 'casualty' | 'inspections' | 'sales_purchase_demolitions' | 'ownership' | 'class_society' | 'engine', required
  - `lat` number, float: Required for inradius_history. Centre latitude.
  - `lon` number, float: Required for inradius_history. Centre longitude.
  - `radius` integer: Required for inradius_history. Radius in nautical miles (max 50).
  - `from` string, date: Start date yyyy-mm-dd. inradius_history max 7-day window; request_usage max 31 days.
  - `to` string, date: End date yyyy-mm-dd.
  - `updated_from` string, date: For add-on bulk reports. Only include records updated on or after this date.

## Response `202`

Job accepted. Poll with the returned report_id.

- object
  - `data` ReportJob
    - `report_id` string
    - `status` '_PENDING_' | '_IN_PROGRESS_' | '_DONE_' | '_FAILED_': Job state. Values are wrapped in underscores. A job can move between `_PENDING_` and `_IN_PROGRESS_` more than once before it finishes. `_FAILED_` is terminal: the report is not retried and never gets a `result_url`.
    - `report_type` string
    - `params` union: The filter parameters the job was submitted with.
      - object
      - string
    - `message` string, nullable: Plain-language reason the job failed. Populated when status is `_FAILED_`.
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `result_url` string, uri, nullable: Signed ZIP download URL, populated only when status is `_DONE_`. The link is valid for 6 hours from when it is issued and returns 403 once it expires. Poll the report again for a fresh link. That is free and does not re-run the report. Use the whole URL including its query string, and request it with GET, not HEAD.
  - `meta` Meta
    - `duration` number, float: Server-side query time in seconds.
    - `endpoint` string
    - `success` boolean
    - `next` string: Pagination token. Present on paginated endpoints (`/vessel_find`) only when more results exist. Pass it back as the `next` query parameter to fetch the following page.

## Other responses

- `400`: Missing required parameter or invalid parameter value.
- `401`: Invalid or expired API key.
- `402`: API key is valid but the credit balance is exhausted or the subscription has expired. Purchase more credits to continue.
- `404`: Requested vessel, port, or resource was not found. No credits deducted.
- `429`: More than 600 API calls in a single minute. The response carries a `Retry-After` header with the wait in seconds. Use it for backoff.
- `500`: Server-side error. Retry the request.

## Changes

- **2026-09-08** `a29cf323d1c3`: 5 warning, 13 info
  - deleted the `query` request parameter `api-key`
  - added the new `_DONE_` enum value to the `data/status` response property for the response status `202`
  - added the new `_FAILED_` enum value to the `data/status` response property for the response status `202`
  - added the new `_IN_PROGRESS_` enum value to the `data/status` response property for the response status `202`
  - …14 more

[Operation history](https://skmtc.dev/datalastic/apis/datalastic-maritime-api/changes/api/v0/report/post.md)

---

[API](https://skmtc.dev/datalastic/apis/datalastic-maritime-api.md) - [All operations](https://skmtc.dev/datalastic/apis/datalastic-maritime-api/llms.txt) - [OpenAPI document](https://skmtc.dev/datalastic/apis/datalastic-maritime-api/revisions/2097cdbffcb4?raw)