---
title: "Vessel details for up to 100 MMSIs and IMO numbers in one request"
method: GET
path: "/v1/vessels/batch"
---

# Vessel details for up to 100 MMSIs and IMO numbers in one request

`GET /v1/vessels/batch`

## Request

- Base URL: `https://api.aistrail.com`
- URL: `https://api.aistrail.com/v1/vessels/batch`
- Auth: HTTP bearer

Each result carries the identifier asked for (query) and the vessel's latest static data, first and last seen, sources, flag, dwt_estimate and sanctions. An IMO number resolves to the MMSI that reported it last. Identifiers not found in the sources of your plan are listed in not_found. 1 credit per vessel returned (a vessel asked for twice counts once).

## Query parameters

- `mmsi` string
- `imo` string

## Response `200`

ok

- object
  - `results` BatchVessel[]
    - `query` object: The identifier asked for: {"mmsi": …} or {"imo": …}
    - `mmsi` integer
    - `imo` integer, nullable
    - `name` string, nullable
    - `callsign` string, nullable
    - `ship_type` integer, nullable
    - `length_m` number, nullable
    - `width_m` number, nullable
    - `draught_m` number, nullable
    - `destination` string, nullable
    - `eta` string, date-time, nullable
    - `first_seen` string, date-time
    - `last_seen` string, date-time
    - `sources` string[]
    - `flag` Flag, nullable: Flag derived from the MMSI's Maritime Identification Digits (ITU MID table). It is the flag of the ship station licence: usually, but not always, the registry flag. null when the MMSI is not a ship station (coast stations, SAR aircraft, AIS-SART/MOB/EPIRB, aids to navigation, handhelds) or its MID is not allocated.
      - `code` string: ISO 3166-1 alpha-2 country or territory code
      - `name` string: English short name
      - `source` 'mmsi'
    - `dwt_estimate` DwtEstimate, nullable: Estimated deadweight from AIS dimensions, not a registry value: tonnes = k x length x beam x draught, with k per hull (block coefficient, waterline length and lightship share folded into one factor) calibrated on vessels with published deadweight. null for implausible dimensions and for ship types where deadweight does not apply or the hull is unknown (tugs, pilot, search and rescue, port and law enforcement craft, military, sailing and pleasure craft, high speed craft, other and unknown types).
      - `tonnes` integer: Estimated deadweight, metric tonnes, rounded to 3 significant digits
      - `class` 'Handysize' | 'MR' | 'Panamax' | 'Aframax' | 'Suezmax' | 'VLCC' | 'ULCC' | 'Handymax' | 'Supramax' | 'Ultramax' | 'Post-Panamax' | 'Capesize' | 'VLOC' | 'Feeder' | 'New Panamax' | 'ULCV' | 'null', nullable: Industry size class: by estimated deadweight for tankers and bulk carriers, by dimensions for container ships; null for passenger and fishing vessels and below 10,000 t
      - `hull` 'tanker' | 'bulk' | 'container' | 'passenger' | 'fishing': Hull family used; for AIS cargo types bulk (dry bulk and general cargo) or container is inferred from the dimensions
      - `draught_m` number: Draught used, metres
      - `draught_source` 'ais_max' | 'typical': ais_max: the deepest draught the vessel has reported; typical: none reported, or too shallow to be a loaded draught, so a typical draught for the beam
      - `method` 'dimensions'
      - `note` string
    - `sanctions` SanctionListing[]: Official sanctions lists that name the card's current IMO number and, for an IMO query, the IMO number asked for (empty when none)
      - `list` 'OFAC' | 'UK' | 'EU': OFAC: the OFAC SDN List; UK: the UK Sanctions List; EU: Annex XLII of Council Regulation (EU) No 833/2014 (vessels under the Article 3s port and services ban)
      - `programmes` string[]: Sanctions programmes or regimes as written on the list
      - `listed` string, date, nullable: Date the vessel was designated, as published on the list
      - `name` string, nullable: Vessel name on the list
      - `ref` string, nullable: The list's own identifier for the entry
  - `not_found` object[]: Identifiers without a vessel, e.g. {"mmsi": 123456789}
  - `meta` ResponseMeta
    - `embargo_cutoff` string, date-time, nullable: Data newer than this is not available on your plan (null on plans with live data)
    - `sources_through` object: Per source: the archive holds this source's data up to this time, never later than embargo_cutoff (null: no data yet)
    - `private_vessels` 'excluded' | 'included': Whether private vessels are part of this response for your account
    - `attribution` object[]: Required attribution for the sources in this response
    - `sanctions_lists` SanctionsLists: The sanctions lists checked for this response: per list its publication date, when AIS Trail fetched it and how many vessels it names (stale: the last fetch failed, the previous copy is used), plus a note
      - `lists` object
      - `note` string
    - `notice` string: Not-for-navigation notice (also in the X-Notice header)

## Other responses

- `400`: RFC 9457 problem details
- `401`: RFC 9457 problem details
- `402`: RFC 9457 problem details
- `429`: RFC 9457 problem details
- `503`: RFC 9457 problem details

---

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