---
title: "Quickstart"
description: "Start here as a developer to create an API key, query Earth data, and run a small workflow."
image: "https://tilebox.com/images/tilebox-docs-social-preview.png"
---

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

# Quickstart

import { CardGrid } from "@docs/components/ui/card-grid";
import { Steps } from "@docs/components/ui/steps";
import { LinkCard } from "@docs/components/ui/link-card";

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](/docs/ai/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](/docs/sdks/python/install).

## Start in a Notebook

Explore the provided [Sample Notebooks](/docs/sdks/python/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](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
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](/docs/console)

- [CLI](/docs/cli)

- [Go SDK](/docs/sdks/go/install)

- [Agents](/docs/ai/onboard-your-agent)

- [Notebooks](/docs/sdks/python/sample-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 title="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 title="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:

        Learn how to create a custom dataset catalog with the Python SDK.

        Learn how to ingest GeoParquet metadata into an existing spatio-temporal catalog.

        Inspect task state, logs and traces when a workflow job fails.

        Package a Python workflow project, publish a release, and deploy it to a cluster.

        Use a coding agent with the Tilebox CLI to build, deploy, run, and debug workflow releases.

Source: https://tilebox.com/docs/quickstart/index.mdx