Datasets

List Datasets

get

List datasets with optional filtering.

Returns a flat list of datasets with offset-based pagination. For iterating over large or unbounded result sets, prefer GET /v1/datasets/cursor which uses cursor-based pagination and guarantees stable ordering across pages.

All filters are combined with AND logic. When multiple tags are specified, only datasets matching all of them are returned.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Query parameters

nameany ofOptional

Case-insensitive substring search on dataset name.

stringOptional

or

nullOptional

created_afterany ofOptional

Filter datasets created after this ISO 8601 timestamp.

string · date-timeOptional

or

nullOptional

created_beforeany ofOptional

Filter datasets created before this ISO 8601 timestamp.

string · date-timeOptional

or

nullOptional

limitinteger · min: 1 · max: 1000OptionalDefault: 100

offsetintegerOptionalDefault: 0

bboxany ofOptional

Bounding box as comma-separated values: 'min_lon,min_lat,max_lon,max_lat'. If you want to query a single location, you can use the same value for min and max. All values should be in EPSG:4326 coordinates.

Example: 12.34,56.78,23.45,67.89

stringOptional

or

nullOptional

tagany ofOptional

Tag filter as repeated query params. Format: '?tag=key1:value1&tag=key2:value2'. Use ':' for a literal colon, '\' for a literal backslash. Datasets must match ALL specified tags.

Example: sensor:sentinel-2

string[]Optional

or

nullOptional

Header parameters

x-earthscale-api-keyany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Single entry in the list of datasets with a subset of information

dataset_idstring · uuidRequired

dataset_version_idstring · uuidRequired

namestringRequired

typestring · enumRequiredPossible values:

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

422

Validation Error

application/json

get

/datasets

HTTPcURLJavaScriptPython

GET /v1/datasets HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "dataset_id": "123e4567-e89b-12d3-a456-426614174000",
    "dataset_version_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "type": "raster",
    "labels": [
      {
        "name": "text",
        "value": "text"
      }
    ],
    "tags": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "created_at": "2026-03-20T17:14:19.106Z",
    "updated_at": "2026-03-20T17:14:19.106Z"
  }
]

Add Dataset

post

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Header parameters

x-earthscale-api-keyany ofOptional

stringOptional

or

nullOptional

Body

application/json

or

or

or

Responses

200

Successful Response

application/json

dataset_idstring · uuidRequired

dataset_version_idstring · uuidRequired

422

Unable to process the request (e.g. unsupported dataset type, source files not accessible)

application/json

post

/datasets

HTTPcURLJavaScriptPython

POST /v1/datasets HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 298

{
  "name": "my_dataset",
  "tags": {
    "key": "value"
  },
  "visualization_optimization": "auto",
  "pixel_info_optimizations": [
    "time"
  ],
  "type": "image",
  "urls": "gs://example-bucket/image_*.tif",
  "bands": [
    "band1",
    "band2"
  ],
  "filename_date_pattern": "%Y-%m-%d",
  "filename_band_pattern": {
    "band": "band1",
    "pattern": "image_*.tif"
  }
}

{
  "dataset_id": "123e4567-e89b-12d3-a456-426614174000",
  "dataset_version_id": "123e4567-e89b-12d3-a456-426614174000"
}

Delete Dataset

delete

Soft-delete a dataset.

Deletion works by creating a new dataset version that marks the dataset as deleted. This hides the dataset from the catalog and listing APIs, but tiling requests for existing versions are still accepted. Optionally removes the dataset from all maps.

Both dataset IDs and dataset version IDs are accepted — it does not matter which is passed, the entire dataset is deleted either way.

Returns the dataset ID and the ID of the newly created deletion marker version.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Path parameters

dataset_idstring · uuidRequired

Query parameters

remove_from_mapsbooleanOptionalDefault: true

Header parameters

x-earthscale-api-keyany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

dataset_idstring · uuidRequired

dataset_version_idstring · uuidRequired

404

Dataset not found

application/json

409

Dataset is already deleted

application/json

422

Validation Error

application/json

delete

/datasets/{dataset_id}

HTTPcURLJavaScriptPython

DELETE /v1/datasets/{dataset_id} HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "dataset_id": "123e4567-e89b-12d3-a456-426614174000",
  "dataset_version_id": "123e4567-e89b-12d3-a456-426614174000"
}

List Datasets (Cursor Pagination)

get

List datasets with cursor-based pagination (recommended).

This is the preferred endpoint for iterating over datasets. It returns a paginated response with a next_cursor token. Pass the token back as the cursor query parameter to fetch the next page. When next_cursor is null, all results have been returned.

Supports the same filters as GET /v1/datasets. All filters are combined with AND logic. When multiple tags are specified, only datasets matching all of them are returned.

Results are ordered by updated_at descending, then by dataset version ID for stable ordering across pages.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Query parameters

nameany ofOptional

Case-insensitive substring search on dataset name.

stringOptional

or

nullOptional

created_afterany ofOptional

Filter datasets created after this ISO 8601 timestamp.

string · date-timeOptional

or

nullOptional

created_beforeany ofOptional

Filter datasets created before this ISO 8601 timestamp.

string · date-timeOptional

or

nullOptional

cursorany ofOptional

Opaque cursor token from a previous paginated response.

stringOptional

or

nullOptional

limitinteger · min: 1 · max: 1000OptionalDefault: 100

bboxany ofOptional

Bounding box as comma-separated values: 'min_lon,min_lat,max_lon,max_lat'. If you want to query a single location, you can use the same value for min and max. All values should be in EPSG:4326 coordinates.

Example: 12.34,56.78,23.45,67.89

stringOptional

or

nullOptional

tagany ofOptional

Tag filter as repeated query params. Format: '?tag=key1:value1&tag=key2:value2'. Use ':' for a literal colon, '\' for a literal backslash. Datasets must match ALL specified tags.

Example: sensor:sentinel-2

string[]Optional

or

nullOptional

Header parameters

x-earthscale-api-keyany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Paginated list of datasets with cursor-based pagination

next_cursorany ofOptional

stringOptional

or

nullOptional

422

Validation Error

application/json

get

/datasets/cursor

HTTPcURLJavaScriptPython

GET /v1/datasets/cursor HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "data": [
    {
      "dataset_id": "123e4567-e89b-12d3-a456-426614174000",
      "dataset_version_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "type": "raster",
      "labels": [
        {
          "name": "text",
          "value": "text"
        }
      ],
      "tags": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "created_at": "2026-03-20T17:14:19.106Z",
      "updated_at": "2026-03-20T17:14:19.106Z"
    }
  ],
  "next_cursor": "text"
}

Get Latest Dataset Version

get

Get the latest version of a dataset by dataset ID.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Path parameters

dataset_idstring · uuidRequired

Header parameters

x-earthscale-api-keyany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

dataset_idstring · uuidRequired

dataset_version_idstring · uuidRequired

namestringRequired

typestring · enumRequiredPossible values:

created_atstring · date-timeRequired

optimized_tile_serverany ofRequired

or

nullOptional

422

Validation Error

application/json

get

/datasets/{dataset_id}/latest

HTTPcURLJavaScriptPython

GET /v1/datasets/{dataset_id}/latest HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "dataset_id": "123e4567-e89b-12d3-a456-426614174000",
  "dataset_version_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "type": "raster",
  "labels": [
    {
      "name": "text",
      "value": "text"
    }
  ],
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": {
      "sampled_min": 1,
      "sampled_max": 1
    }
  },
  "created_at": "2026-03-20T17:14:19.106Z",
  "visualization_optimization": {
    "status": "not_started",
    "updated_at": "2026-03-20T17:14:19.106Z"
  },
  "pixel_info_optimizations": {
    "ANY_ADDITIONAL_PROPERTY": {
      "status": "not_started",
      "updated_at": "2026-03-20T17:14:19.106Z"
    }
  },
  "dynamic_tile_server": {
    "tile_url": "text",
    "pixel_url": "text",
    "min_zoom": 1,
    "max_zoom": 1
  },
  "optimized_tile_server": {
    "tile_url": "text",
    "pixel_url": "text",
    "min_zoom": 1,
    "max_zoom": 1
  }
}

Get Dataset Version By Id

get

Get a dataset version by version ID.

Authorizations

OAuth2PasswordBearer

OAuth2passwordRequired

Token URL:

Path parameters

version_idstring · uuidRequired

Header parameters

x-earthscale-api-keyany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

dataset_idstring · uuidRequired

dataset_version_idstring · uuidRequired

namestringRequired

typestring · enumRequiredPossible values:

created_atstring · date-timeRequired

optimized_tile_serverany ofRequired

or

nullOptional

422

Validation Error

application/json

get

/dataset-versions/{version_id}

HTTPcURLJavaScriptPython

GET /v1/dataset-versions/{version_id} HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "dataset_id": "123e4567-e89b-12d3-a456-426614174000",
  "dataset_version_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "type": "raster",
  "labels": [
    {
      "name": "text",
      "value": "text"
    }
  ],
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": {
      "sampled_min": 1,
      "sampled_max": 1
    }
  },
  "created_at": "2026-03-20T17:14:19.106Z",
  "visualization_optimization": {
    "status": "not_started",
    "updated_at": "2026-03-20T17:14:19.106Z"
  },
  "pixel_info_optimizations": {
    "ANY_ADDITIONAL_PROPERTY": {
      "status": "not_started",
      "updated_at": "2026-03-20T17:14:19.106Z"
    }
  },
  "dynamic_tile_server": {
    "tile_url": "text",
    "pixel_url": "text",
    "min_zoom": 1,
    "max_zoom": 1
  },
  "optimized_tile_server": {
    "tile_url": "text",
    "pixel_url": "text",
    "min_zoom": 1,
    "max_zoom": 1
  }
}