Get all Bulk Download reports by User

Use this endpoint to retrieve all bulk reports created by your user or application. It supports pagination, sorting, and optional filtering by status or API dataset (see list of datasets available here). You can filter by the API dataset alias, such as public-fixed-infrastructure-data:latest, or by the resolved versioned value returned in the report response, such as public-fixed-infrastructure-data:v1.1.

EXAMPLE (GET) – Retrieve list of bulk reports sorted by creation date

# Make sure to replace [TOKEN] with your API Access Token.
curl --location 'https://gateway.api.globalfishingwatch.org/v3/bulk-reports?limit=10&offset=5&sort=-createdAt&dataset=public-fixed-infrastructure-data:latest' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [TOKEN]'

// Make sure to replace [TOKEN] with your API Access Token.
const res = await fetch(
  'https://gateway.api.globalfishingwatch.org/v3/bulk-reports?limit=10&offset=5&sort=-createdAt&dataset=public-fixed-infrastructure-data:latest',
  { headers: { Authorization: 'Bearer [TOKEN]' } }
)
const data = await res.json()

EXAMPLE: RESPONSE (GET) – Retrieve list of bulk reports sorted by creation date

   {
  "metadata": {},
  "limit": 10,
  "offset": 5,
  "nextOffset": null,
  "total": 10,
  "entries": [
    {
      "id": "d16d2d2a-b415-4f47-a525-54d60c0db2cd",
      "dataset": "public-fixed-infrastructure-data:v1.1",
      "name": "sar-vessel-detection-example-1",
      "filepath": "sar_fixed_infrastructure_202409.csv",
      "filters": [
        "label = 'oil'",
        "structure_start_date between '2020-01-01' and '2025-01-01'"
      ],
      "status": "done",
      "geom": {
        "id": 8466,
        "type": "dataset",
        "dataset": "public-eez-areas"
      },
      "createdAt": "2025-06-24T14:21:27.517Z",
      "updatedAt": "2025-06-24T14:21:27.517Z",
      "ownerId": 385,
      "ownerType": "user-application",
      "format": "CSV",
      "fileSize": 1207
    }
  ]
}

Bulk Reports GET - Specifications

GET https://gateway.api.globalfishingwatch.org/v3/bulk-reports

Authorization

ApiKeyAuth

AuthorizationBearer <token>

In: header

Query Parameters

limit*number

Amount of search results to return.

Range1 <= value

offset*number

Offset into the search results, used for pagination. It starts at 0. It is used in combination with the param “limit”. For example, you send limit = 5 and you get in the response total vessels =10. So, If you send offset =0, you will get the first 5 results (first page). Therefore, in order to get the second page, you need to send offset = 5 which is the position of the first element you want from the second page.

Range0 <= value

sort?string

Query to sort the list of resources. The column name must exists in the data to retrieve

status?string

Optional. Filter by status

Value in

"pending"
"processing"
"done"
"failed"

dataset?string

Optional. Filter by dataset id

curl -X GET "https://example.com/api/v3/bulk-reports?limit=1&offset=0"

{  "entries": [    {      "createdAt": "2019-08-24T14:15:22Z",      "dataset": "string",      "fileSize": 0,      "filepath": "fixed_infrastructure_202407.csv",      "filters": [        "type = 'fishing'"      ],      "format": "",      "geom": {},      "id": "",      "name": "my-report",      "ownerId": 0,      "ownerType": "string",      "status": "pending",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "limit": 10,  "metadata": {},  "nextOffset": 10,  "offset": 0,  "total": 152}

{  "error": "Unauthorized",  "messages": [    {      "detail": "No authorized",      "metadata": {},      "title": "Unauthorized"    }  ],  "statusCode": 401}

{  "error": "Forbidden",  "messages": [    {      "detail": "You do not have permissions to do the action",      "metadata": {},      "title": "Forbidden"    }  ],  "statusCode": 403}

{  "error": "Unprocessable Entity",  "messages": [    {      "detail": "Validation exception",      "metadata": {},      "title": "Unprocessable Entity"    }  ],  "statusCode": 422}

{  "error": "Service Unavailable",  "messages": [    {      "detail": "Service unavailable",      "metadata": {},      "title": "Service Unavailable"    }  ],  "statusCode": 503}

Bulk Reports GET - Response fields

Name	Type	Required	Restrictions	Description
`metadata`	object	false	—	Contains metadata related to the query, such as dataset or filters used.
`limit`	number	true	≥ 1	Number of items returned in this response.
`offset`	number	true	≥ 0	Offset position of the first item in the response.
`nextOffset`	number	false	≥ 0	Offset for the next page of results, if available.
`total`	number	true	≥ 0	Total number of matching reports available for the user.
`entries`	array	true	—	List of bulk reports matching the request. Each entry contains the fields below.
`id`	string	true	UUID	Unique identifier of the bulk report.
`dataset`	string	true	e.g. `public-fixed-infrastructure-data:v1.1`	API dataset used to generate the bulk report. The response may contain the resolved version of an alias such as `latest`.
`name`	string	true	—	Human-readable name of the bulk report.
`filepath`	string	true	filename	Name of the output file generated by the report.
`filters`	array	false	—	Array of string filters used when generating the report.
`status`	string	true	Enum: `pending`, `processing`, `done`, `failed`	Current status of the report generation process.
`geom.id`	number	true	—	ID of the geometry used to define the report region.
`geom.type`	string	true	Enum: `dataset`, `geojson`	Type of geometry input.
`geom.dataset`	string	true	e.g., `public-eez-areas`	Dataset associated with the region if using reference geometry.
`createdAt`	string	true	ISO 8601	Timestamp when the report was created.
`updatedAt`	string	true	ISO 8601	Timestamp when the report was last updated.
`ownerId`	number	true	—	ID of the user or application that created the report.
`ownerType`	string	true	Enum: `user-application`	Type of entity that created the report.
`format`	string	true	Enum: `CSV`, `JSON`	Format of the generated report file.
`fileSize`	number	false	≥ 0 (in bytes)	Size of the output file in bytes.

Bulk Reports GET - Status Responses

Status	Meaning	Description	Schema
200	OK	Successfully retrieved the list of bulk reports.	Bulk Report Response properties
401	Unauthorized	Your request did not include a valid API token.	Error Codes
403	Forbidden	You do not have permission to access these reports.	Error Codes
422	Unprocessable Entity	Your query parameters are invalid or malformed.	Error Codes
500	Internal Server Error	A server-side issue occurred. Please contact us at [email protected]	Error Codes