Quickstart

Start here as a developer to create an API key, query Earth data, and run a small workflow.

This quickstart is for developers using Tilebox directly from a terminal, notebook, or SDK. If you want an AI coding agent to work with Tilebox for you, start with Onboard your agent.

You will create an API key, query open Sentinel-2 metadata, and run a small workflow task using the Tilebox Python SDK.

Start in a Notebook

Explore the provided Sample Notebooks to begin your journey with Tilebox. These notebooks offer a step-by-step guide to using the API and showcase many features supported by Tilebox Python clients. You can also use these notebooks as a foundation for your own projects.

Start on Your Device

If you prefer to work locally, follow these steps to get started.

Create an API Key
Create an API key by logging into the Tilebox Console, navigating to Settings → API Keys, and clicking the “Create API Key” button.
Then, add it to your environment
Terminal window
```
export TILEBOX_API_KEY=<your-api-key>
```
Choose your working environment
Tilebox can be used from the browser, terminal, or via our SDKs running locally or in interactive notebook environments. This quickstart guides you through setting up the Tilebox Python SDK locally. Alternatively, you can also check out any of the following ways of using Tilebox.
Console Command line Go SDK Agents Notebooks
To install the python SDK locally, run the following command.
Terminal window
```
uv add tilebox
```

Query Data

Use the datasets client to query data from a dataset.

from tilebox.datasets import Client
from shapely import Polygon

# define a search area (optional)
new_york_city = Polygon(
    [(-74.40, 41.02), (-74.48, 40.27), (-73.37, 40.34),
    (-73.39, 41.05), (-74.40, 41.02)]
)

client = Client(token="YOUR_TILEBOX_API_KEY")

# select a dataset
dataset = client.dataset("open_data.copernicus.sentinel2_msi")
# and query data
scenes_new_york_january_2026 = dataset.query(
  collections=["S2A_S2MSI2A", "S2B_S2MSI2A", "S2C_S2MSI2A"],
  temporal_extent=("2026-01-01", "2026-02-01"),
  spatial_extent=new_york_city
)
print(scenes_new_york_january_2026.granule_name)

Run a Workflow

Use the workflows client to create a task and submit it as a job.

from tilebox.workflows import Client, Runner, Task
from tilebox.workflows.observability.logging import configure_console_logging

configure_console_logging()

# Replace with your actual token
client = Client(token="YOUR_TILEBOX_API_KEY")

class HelloWorldTask(Task):
    greeting: str = "Hello"
    name: str = "World"

    def execute(self, context):
        context.logger.info(f"{self.greeting} {self.name}, from the main task!")
        context.submit_subtask(HelloSubtask(name=self.name))

class HelloSubtask(Task):
    name: str

    def execute(self, context):
        context.logger.info(f"Hello from the subtask!", name=self.name)

# Initiate the job
jobs = client.jobs()
job = jobs.submit("parameterized-hello-world", HelloWorldTask(greeting="Greetings", name="Universe"))

# Run the tasks
runner = Runner(tasks=[HelloWorldTask, HelloSubtask])
runner.connect_to(client).run_all()

print("Explore the job you just submitted in the Tilebox Console.")
print("Check out tasks, log messages, and execution timining:")
print(f"https://console.tilebox.com/workflows/jobs/{job.id}")

Explore Further

Review the following guides to learn more about the modules that make up Tilebox:
Build a spatio-temporal catalog
Learn how to create a custom dataset catalog with the Python SDK.
Ingest into a spatio-temporal catalog
Learn how to ingest GeoParquet metadata into an existing spatio-temporal catalog.
Debug a failed workflow run
Inspect task state, logs and traces when a workflow job fails.
Build and deploy a workflow project
Package a Python workflow project, publish a release, and deploy it to a cluster.
Agentic workflow iteration
Use a coding agent with the Tilebox CLI to build, deploy, run, and debug workflow releases.