Skip to content
Docs
Console

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.

  1. 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

    bash 
    export TILEBOX_API_KEY=<your-api-key>

  2. 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

    CLI

    Go SDK

    Agents

    Notebooks

    To install the python SDK locally, run the following command.

    bash 
    uv add tilebox

  3. Query Data

    Use the datasets client to query data from a dataset.

    Python 
    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)

  4. Run a Workflow

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

    Python 
    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}")

  5. 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.
Docs

Type to search…