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

# Quickstart

> Create, trigger, and observe your first flow in five minutes

This walkthrough creates a minimal flow using the built-in `echo` action (no external connection needed), triggers it, and follows the run through to its result.

<Info>
  You'll need an API key. Export it as `GETDIALED_API_KEY` and set the base URL — `https://api.getdialed.ai/flows` in production.
</Info>

```bash theme={null}
export BASE_URL="https://api.getdialed.ai/flows"
export GETDIALED_API_KEY="<your key>"
```

## 1. Create a Flow Definition

A definition declares its **inputs**, then a series of **steps** containing **tasks**. This one has a single step with a single task that echoes a message built from the trigger input:

```bash theme={null}
curl -X POST "$BASE_URL/definitions" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hello GetDialed",
    "status": "active",
    "inputs": [
      {"name": "message", "type": "string", "required": true}
    ],
    "steps": [
      {
        "step_id": "step_1",
        "name": "Echo the input",
        "tasks": [
          {
            "task_id": "task_1",
            "task_name": "echo",
            "platform_id": "getdialed",
            "service_id": "getdialed__utils",
            "action_id": "getdialed__utils__echo",
            "parameters": {
              "message": "{{input.message}}"
            }
          }
        ]
      }
    ]
  }'
```

The response includes the new definition's `id` (e.g. `def_a1b2c3d4`). Note `"status": "active"` — only active definitions can be triggered.

<Tip>
  `{{input.message}}` is an [expression](/concepts/expressions). At runtime it resolves to the `message` field of the trigger's `input_data`.
</Tip>

## 2. Trigger it

```bash theme={null}
curl -X POST "$BASE_URL/definitions/def_a1b2c3d4/trigger" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_data": {"message": "hello, world"}
  }'
```

```json theme={null}
{
  "job_id": "job_9f8e7d6c",
  "definition_id": "def_a1b2c3d4",
  "status": "pending"
}
```

Every trigger creates a **Job**. This one carries a single record, so it produces one **Execution**. To run the same flow for many records at once (e.g. rows of an uploaded file), pass a `records` array instead — see [Triggering with records](/guides/trigger-with-records).

## 3. Watch it run

Fetch the job:

```bash theme={null}
curl "$BASE_URL/jobs/job_9f8e7d6c" \
  -H "X-API-Key: $GETDIALED_API_KEY"
```

The job's status moves `pending → running → completed`. List its executions to see per-record results:

```bash theme={null}
curl "$BASE_URL/jobs/job_9f8e7d6c/executions" \
  -H "X-API-Key: $GETDIALED_API_KEY"
```

Each execution has its own `status`, `result`, and — on failure — an `error` message.

## Next steps

<CardGroup cols={2}>
  <Card title="Jobs & Executions" icon="diagram-project" href="/concepts/jobs-and-executions">
    The full lifecycle: triggers, jobs, executions, and statuses.
  </Card>

  <Card title="Trigger with records" icon="table" href="/guides/trigger-with-records">
    Fan a file of records out into one execution per row.
  </Card>

  <Card title="Connections" icon="plug" href="/concepts/connections">
    Store credentials for real integrations like Five9.
  </Card>

  <Card title="Build a real flow" icon="hammer" href="/guides/build-your-first-flow">
    A multi-step flow against a live integration.
  </Card>
</CardGroup>