> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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](/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](/sdks/python).

## Start in a Notebook

Explore the provided [Sample Notebooks](/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.

<Steps>
  <Step title="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>
    ```
  </Step>

  <Step title="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.

    <CardGroup cols={2}>
      <Card title="Console" icon="display" href="/console" horizontal />

      <Card title="Command line" icon="terminal" href="/agents-and-ai-tools/tilebox-cli" horizontal />

      <Card title="Go SDK" icon="golang" href="/sdks/go" horizontal />

      <Card title="Agents" icon="robot" href="/onboard-your-agent" horizontal />

      <Card title="Notebooks" icon="book-open" href="/sdks/python/sample-notebooks" horizontal />
    </CardGroup>

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

    ```bash theme={"system"}
    uv add tilebox
    ```
  </Step>

  <Step title="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)
    ```
  </Step>

  <Step title="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}")
    ```
  </Step>

  <Step title="Explore Further">
    Review the following guides to learn more about the modules that make up Tilebox:

    <Columns cols={1}>
      <Card title="Build a spatio-temporal catalog" icon="database" href="/guides/datasets/build-spatiotemporal-catalog" horizontal>
        Learn how to create a custom dataset catalog with the Python SDK.
      </Card>

      <Card title="Ingest into a spatio-temporal catalog" icon="up-from-bracket" href="/guides/datasets/ingest-into-spatiotemporal-catalog" horizontal>
        Learn how to ingest GeoParquet metadata into an existing spatio-temporal catalog.
      </Card>

      <Card title="Debug a failed workflow run" icon="bug" href="/guides/workflows/debug-failed-run" horizontal>
        Inspect task state, logs and traces when a workflow job fails.
      </Card>

      <Card title="Build and deploy a workflow project" icon="rocket" href="/guides/workflows/build-and-deploy-workflow" horizontal>
        Package a Python workflow project, publish a release, and deploy it to a cluster.
      </Card>

      <Card title="Agentic workflow iteration" icon="robot" href="/guides/workflows/agentic-workflow-iteration" horizontal>
        Use a coding agent with the Tilebox CLI to build, deploy, run, and debug workflow releases.
      </Card>
    </Columns>
  </Step>
</Steps>