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

OAuth2passwordRequired

Token URL:

Query parameters

namestring · nullableOptional

Case-insensitive substring search on dataset name.

created_afterstring · date-time · nullableOptional

Filter datasets created after this ISO 8601 timestamp.

created_beforestring · date-time · nullableOptional

Filter datasets created before this ISO 8601 timestamp.

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

offsetintegerOptionalDefault: 0

bboxstring · nullableOptional

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

tagstring[] · nullableOptional

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

Header parameters

x-earthscale-api-keystring · nullableOptional

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

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-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
]

Add Dataset

post

Authorizations

OAuth2passwordRequired

Token URL:

Header parameters

x-earthscale-api-keystring · nullableOptional

Body

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

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

OAuth2passwordRequired

Token URL:

Path parameters

dataset_idstring · uuidRequired

Query parameters

remove_from_mapsbooleanOptionalDefault: true

Header parameters

x-earthscale-api-keystring · nullableOptional

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}

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

OAuth2passwordRequired

Token URL:

Query parameters

namestring · nullableOptional

Case-insensitive substring search on dataset name.

created_afterstring · date-time · nullableOptional

Filter datasets created after this ISO 8601 timestamp.

created_beforestring · date-time · nullableOptional

Filter datasets created before this ISO 8601 timestamp.

cursorstring · nullableOptional

Opaque cursor token from a previous paginated response.

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

bboxstring · nullableOptional

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

tagstring[] · nullableOptional

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

Header parameters

x-earthscale-api-keystring · nullableOptional

Responses

200

Successful Response

application/json

Paginated list of datasets with cursor-based pagination

next_cursorstring · nullableOptional

422

Validation Error

application/json

get/datasets/cursor

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-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": "text"
}

Get Latest Dataset Version

get

Get the latest version of a dataset by dataset ID.

Authorizations

OAuth2passwordRequired

Token URL:

Path parameters

dataset_idstring · uuidRequired

Header parameters

x-earthscale-api-keystring · nullableOptional

Responses

200

Successful Response

application/json

dataset_idstring · uuidRequired

dataset_version_idstring · uuidRequired

namestringRequired

typestring · enumRequiredPossible values:

created_atstring · date-timeRequired

422

Validation Error

application/json

get/datasets/{dataset_id}/latest

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-01-01T00:00:00.000Z",
  "visualization_optimization": {
    "status": "not_started",
    "updated_at": "2026-01-01T00:00:00.000Z"
  },
  "pixel_info_optimizations": {
    "ANY_ADDITIONAL_PROPERTY": {
      "status": "not_started",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  },
  "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

OAuth2passwordRequired

Token URL:

Path parameters

version_idstring · uuidRequired

Header parameters

x-earthscale-api-keystring · nullableOptional

Responses

200

Successful Response

application/json

dataset_idstring · uuidRequired

dataset_version_idstring · uuidRequired

namestringRequired

typestring · enumRequiredPossible values:

created_atstring · date-timeRequired

422

Validation Error

application/json

get/dataset-versions/{version_id}

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-01-01T00:00:00.000Z",
  "visualization_optimization": {
    "status": "not_started",
    "updated_at": "2026-01-01T00:00:00.000Z"
  },
  "pixel_info_optimizations": {
    "ANY_ADDITIONAL_PROPERTY": {
      "status": "not_started",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  },
  "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
  }
}