> ## Documentation Index
> Fetch the complete documentation index at: https://docs-old.tilebox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs-old.tilebox.com/onboard-your-agent.md).

You will create an API key, query open Sentinel-2 metadata, and run a small workflow task using the Tilebox [Python SDK](https://docs-old.tilebox.com/sdks/python).

## Start in a Notebook

Explore the provided [Sample Notebooks](https://docs-old.tilebox.com/sdks/python/sample-notebooks.md) 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](https://console.tilebox.com), navigating to [Settings -> API Keys](https://console.tilebox.com/settings/api-keys), and clicking the "Create API Key" button.

Then, add it to your environment

```bash theme={"system"}
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.

> [card] [Console](https://docs-old.tilebox.com/console.md)

> [card] [Command line](https://docs-old.tilebox.com/agents-and-ai-tools/tilebox-cli.md)

> [card] [Go SDK](https://docs-old.tilebox.com/sdks/go)

> [card] [Agents](https://docs-old.tilebox.com/onboard-your-agent.md)

> [card] [Notebooks](https://docs-old.tilebox.com/sdks/python/sample-notebooks.md)

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

```bash theme={"system"}
uv add tilebox
```

**3. Query Data**

Use the datasets client to query data from a dataset.

```python Python theme={"system"}
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 Python theme={"system"}
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:

> [card] [Build a spatio-temporal catalog](https://docs-old.tilebox.com/guides/datasets/build-spatiotemporal-catalog.md)
>
> Learn how to create a custom dataset catalog with the Python SDK.

> [card] [Ingest into a spatio-temporal catalog](https://docs-old.tilebox.com/guides/datasets/ingest-into-spatiotemporal-catalog.md)
>
> Learn how to ingest GeoParquet metadata into an existing spatio-temporal catalog.

> [card] [Debug a failed workflow run](https://docs-old.tilebox.com/guides/workflows/debug-failed-run.md)
>
> Inspect task state, logs and traces when a workflow job fails.

> [card] [Build and deploy a workflow project](https://docs-old.tilebox.com/guides/workflows/build-and-deploy-workflow.md)
>
> Package a Python workflow project, publish a release, and deploy it to a cluster.

> [card] [Agentic workflow iteration](https://docs-old.tilebox.com/guides/workflows/agentic-workflow-iteration.md)
>
> Use a coding agent with the Tilebox CLI to build, deploy, run, and debug workflow releases.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.