# MotherDuck Documentation - Flights

> SQL table functions for creating, scheduling, running, and inspecting MotherDuck Flights.

Generated: 2026-08-25

> MotherDuck is a serverless cloud data warehouse built on DuckDB.
It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics.

## Key capabilities

- **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses)
- **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session
- **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language
- **Data Sharing**: Share databases and query results with team members and external users
- **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI
- **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more
- **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation

## When to use MotherDuck

Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP.

## Agent guidance

If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation.

For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows.

To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question.

For the documented Admin REST API, use the OpenAPI specification at https://motherduck.com/docs/openapi.json.

## Account setup for agents

If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request.

`POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`.

Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership.

Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup.

## Included documentation

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/flights

# Flights functions
> SQL table functions for creating, scheduling, running, and inspecting MotherDuck Flights.
SQL table functions for managing [Flights](/concepts/flights), MotherDuck's scheduled Python execution. Use these functions from any MotherDuck client (DuckDB CLI, BI tool, or another Flight) to create, schedule, list, and monitor Flights without leaving SQL.

The MCP server exposes the same operations to AI agents through `create_flight`, `list_flights`, `run_flight`, and so on. The MCP and SQL surfaces use slightly different parameter names — see each function page for the details, or read the [Flights MCP reference](/sql-reference/mcp/) for the agent-facing tools.

:::note
These functions execute server-side on MotherDuck. They are not available on local-only DuckDB connections.
:::

A minimal end-to-end Flight from SQL:

```sql
-- Create the Flight
SELECT flight_id, current_version
FROM MD_CREATE_FLIGHT(
    name := 'heartbeat',
    source_code := $$
import duckdb

def main():
    con = duckdb.connect("md:")
    con.execute("CREATE DATABASE IF NOT EXISTS flights_demo")
    print("ok")

if __name__ == "__main__":
    main()
$$,
    requirements_txt := 'duckdb==1.5.3'
);

-- Trigger an on-demand run
CALL MD_RUN_FLIGHT(flight_id := '<flight_id>');

-- Inspect the run
SELECT run_number, status, created_at
FROM MD_LIST_FLIGHT_RUNS(flight_id := '<flight_id>')
ORDER BY run_number DESC LIMIT 1;
```

## Available functions

## Included pages

- [MD_CREATE_FLIGHT](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-create-flight): Create a new Flight in your MotherDuck account.
- [MD_UPDATE_FLIGHT](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-update-flight): Update a Flight's source code, requirements, config, token, secrets, name, or schedule.
- [MD_DELETE_FLIGHT](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-delete-flight): Delete a Flight, its versions, runs, and logs.
- [MD_GET_FLIGHT](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-get-flight): Fetch the summary metadata for a single Flight.
- [MD_GET_FLIGHT_VERSION](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-get-flight-version): Fetch the full content (source, requirements, config, token, secrets) for a specific Flight version.
- [MD_LIST_FLIGHTS](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-list-flights): List Flights with summary metadata.
- [MD_LIST_FLIGHT_VERSIONS](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-list-flight-versions): List the version history of a Flight.
- [MD_RUN_FLIGHT](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-run-flight): Trigger an on-demand execution of a Flight using its current version.
- [MD_LIST_FLIGHT_RUNS](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-list-flight-runs): List the execution history of a Flight, newest first.
- [MD_GET_FLIGHT_LOGS](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-get-flight-logs): Read the combined stdout and stderr captured during a Flight run.
- [MD_CANCEL_FLIGHT_RUN](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-cancel-flight-run): Cancel an in-progress Flight run.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-create-flight

# MD_CREATE_FLIGHT
> Create a new Flight in your MotherDuck account.
Creates a new [Flight](/concepts/flights) and returns its summary. The initial version is captured from `source_code`, `requirements_txt`, `config`, `access_token_name`, and `flight_secret_names`.

You are responsible for the code you run and the packages it installs. Flights does not scan customer code or dependencies. Avoid untrusted packages, pin dependency versions, and treat dependency installs as a supply-chain risk.

## Syntax

```sql
SELECT * FROM MD_CREATE_FLIGHT(
    name := 'my_flight',
    source_code := '<python_source>',
    schedule_cron := '0 * * * *',
    requirements_txt := 'duckdb==1.5.3',
    config := MAP {'KEY': 'value'},
    access_token_name := '<token_name>',
    flight_secret_names := ['secret_name']
);
```

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | `VARCHAR` | Yes | Human-readable Flight name. Must be non-empty. |
| `access_token_name` | `VARCHAR` | No | Label of a MotherDuck access token to run the Flight as. The token value is injected into the Flight as `MOTHERDUCK_TOKEN`. Omit it to use the default `MotherDuck Flights` access token for your user. List labels with `SELECT * FROM md_access_tokens();`. |
| `source_code` | `VARCHAR` | Yes | Python source for the Flight. A single-file program, executed as a plain script; end it with `if __name__ == "__main__": main()` to invoke your entrypoint. |
| `schedule_cron` | `VARCHAR` | No | 5-field cron expression in UTC. Omit for an on-demand-only Flight. |
| `requirements_txt` | `VARCHAR` | No | Contents of a `requirements.txt`, one pinned package per line. |
| `config` | `MAP(VARCHAR, VARCHAR)` | No | Non-secret key/value pairs surfaced to the Flight as environment variables. |
| `flight_secret_names` | `VARCHAR[]` | No | List of names of [Flight secrets](/sql-reference/motherduck-sql-reference/create-secret#flight-secrets) (`TYPE FLIGHTS`). Each key in a secret's `PARAMS` map is surfaced to the Flight as an environment variable. |
| `max_runtime_sec` | `UINTEGER` | No | Per-run timeout in seconds. `0` means no timeout. Omit to use your plan's default. A value above your plan's cap is rejected. |

:::note
`source_code` is capped at 200 KB and `requirements_txt` at 20 KB. Load large reference data from object storage at run time instead of embedding it in the source.
:::

## Return columns

| Column | Type | Description |
|---|---|---|
| `flight_id` | `UUID` | Unique identifier of the created Flight. |
| `flight_name` | `VARCHAR` | The Flight name. |
| `schedule_cron` | `VARCHAR` | The cron expression, or `NULL` for on-demand. |
| `schedule_status` | `VARCHAR` | Schedule state, or `NULL` when the Flight has no schedule. |
| `status` | `VARCHAR` | Flight status (for example, `JOB_STATUS_ACTIVE`). Not the schedule state — see `schedule_status`. |
| `current_version` | `UINTEGER` | Always `1` for a newly created Flight. |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | Creation timestamp. |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | Last update timestamp. |
| `owner_name` | `VARCHAR` | The user who owns the Flight — the caller, for a newly created Flight. |

## Examples

Minimal Flight, no schedule:

```sql
SELECT flight_id
FROM MD_CREATE_FLIGHT(
    name := 'heartbeat',
    source_code := 'def main(): print("hello")

if __name__ == "__main__":
    main()'
);
```

Scheduled Flight with config, running as a specific access token:

```sql
SELECT flight_id, current_version
FROM MD_CREATE_FLIGHT(
    name := 'hourly_metrics',
    access_token_name := 'analytics_token',
    source_code := $$
import duckdb

def main():
    con = duckdb.connect("md:")
    con.execute("INSERT INTO analytics.hourly_counts SELECT now(), COUNT(*) FROM events")

if __name__ == "__main__":
    main()
$$,
    requirements_txt := 'duckdb==1.5.3',
    schedule_cron := '0 * * * *',
    config := MAP {'REGION': 'eu-central-1'}
);
```

## Related

- [`MD_UPDATE_FLIGHT`](../md-update-flight) — Modify a Flight's content or metadata.
- [`MD_RUN_FLIGHT`](../md-run-flight) — Trigger an on-demand run.
- [`MD_DELETE_FLIGHT`](../md-delete-flight) — Delete a Flight.
- [`create_flight` MCP tool](/sql-reference/mcp/) — AI-agent equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-update-flight

# MD_UPDATE_FLIGHT
> Update a Flight's source code, requirements, config, token, secrets, name, or schedule.
Updates an existing [Flight](/concepts/flights). Behaves as a PATCH: only the parameters you pass are modified, and unspecified fields are left unchanged.

Updates to `source_code`, `requirements_txt`, `config`, `access_token_name`, or `flight_secret_names` produce a fresh `FlightVersion`. Updates to `name` or `schedule_cron` are metadata-only and do not bump the version.

You are responsible for the code you run and the packages it installs. Flights does not scan customer code or dependencies. Avoid untrusted packages, pin dependency versions, and treat dependency installs as a supply-chain risk.

## Syntax

```sql
CALL MD_UPDATE_FLIGHT(
    flight_id := '<flight_id>',
    name := '<updated_name>',
    schedule_cron := '0 0 * * *',
    source_code := '<updated_python>',
    requirements_txt := '<updated_requirements>',
    config := MAP {'KEY': 'value'},
    access_token_name := '<updated_token_name>',
    flight_secret_names := ['secret_name']
);
```

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `flight_id` | `UUID` | Yes | Identifier of the Flight to update. |
| `name` | `VARCHAR` | No | New Flight name. Must be non-empty when provided. Metadata-only. |
| `schedule_cron` | `VARCHAR` | No | New cron expression (UTC, 5 fields). Pass `''` (empty string) to clear the schedule. Metadata-only. |
| `source_code` | `VARCHAR` | No | New Python source. Bumps the version. |
| `requirements_txt` | `VARCHAR` | No | New `requirements.txt` contents. Bumps the version. |
| `config` | `MAP(VARCHAR, VARCHAR)` | No | Replacement config map (full replace, not merge). Bumps the version. |
| `access_token_name` | `VARCHAR` | No | New access token label. Bumps the version. |
| `flight_secret_names` | `VARCHAR[]` | No | Replacement list of [Flight secret](/sql-reference/motherduck-sql-reference/create-secret#flight-secrets) names (full replace). Bumps the version. |
| `max_runtime_sec` | `UINTEGER` | No | Per-run timeout in seconds. `0` means no timeout. Omit to use your plan's default. A value above your plan's cap is rejected. Bumps the version. |

At least one of the above (besides `flight_id`) must be set.

## Return columns

`MD_UPDATE_FLIGHT` returns the updated `FlightSummary`:

| Column | Type | Description |
|---|---|---|
| `flight_id` | `UUID` | The Flight identifier. |
| `flight_name` | `VARCHAR` | The current name. |
| `schedule_cron` | `VARCHAR` | The current cron expression, or `NULL`. |
| `schedule_status` | `VARCHAR` | Schedule state (for example, `SCHEDULE_STATUS_ACTIVE` or `SCHEDULE_STATUS_DISABLED`), or `NULL` when the Flight has no schedule. |
| `status` | `VARCHAR` | Flight status (for example, `JOB_STATUS_ACTIVE`). Not the schedule state — see `schedule_status`. |
| `current_version` | `UINTEGER` | The current version (incremented for content updates). |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | Original creation timestamp. |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | Most recent update timestamp. |
| `owner_name` | `VARCHAR` | The user who owns the Flight. |

## Behavior

- **Full-replace semantics.** `config` and `flight_secret_names` are replaced, not merged. To change one entry, send the full updated map or list.
- **Carry-forward semantics.** When you patch one content field, the resulting version carries unchanged content fields forward from the previous version.
- **Empty schedule.** `schedule_cron := ''` clears the schedule; omit it to leave the existing schedule untouched. Passing `schedule_cron := ''` to a Flight that already has no schedule returns an error, so only send it when there's a schedule to clear.
- **Definition size limit.** `source_code` is capped at 200 KB and `requirements_txt` at 20 KB. Load large reference data from object storage at run time instead of embedding it in the source.

## Examples

Rename a Flight (metadata-only, no new version):

```sql
CALL MD_UPDATE_FLIGHT(
    flight_id := '<flight_id>',
    name := 'analytics_hourly_sync'
);
```

Update the source (bumps the version):

```sql
CALL MD_UPDATE_FLIGHT(
    flight_id := '<flight_id>',
    source_code := $$
def main():
    print("v2")

if __name__ == "__main__":
    main()
$$
);
```

Clear the schedule, leave everything else:

```sql
CALL MD_UPDATE_FLIGHT(
    flight_id := '<flight_id>',
    schedule_cron := ''
);
```

## Related

- [`MD_CREATE_FLIGHT`](../md-create-flight) — Create a Flight.
- [`MD_GET_FLIGHT`](../md-get-flight) — Inspect the current Flight summary.
- [`MD_LIST_FLIGHT_VERSIONS`](../md-list-flight-versions) — List historical versions.
- [`update_flight` MCP tool](/sql-reference/mcp/) — AI-agent equivalent (uses `md_token_name` / `md_secret_names`).

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-delete-flight

# MD_DELETE_FLIGHT
> Delete a Flight, its versions, runs, and logs.
Deletes a [Flight](/concepts/flights). All associated `FlightVersion` records, runs, and logs are removed. Active or pending runs are cancelled.

Deleting an already-deleted Flight returns a `does not exist` error.

## Syntax

```sql
CALL MD_DELETE_FLIGHT(flight_id := '<flight_id>');
```

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `flight_id` | `UUID` | Yes | Identifier of the Flight to delete. |

## Examples

```sql
CALL MD_DELETE_FLIGHT(flight_id := '80000000-0000-0000-0000-000000000001');
```

After deletion, the Flight is no longer reachable through `MD_LIST_FLIGHTS`, `MD_GET_FLIGHT`, `MD_LIST_FLIGHT_VERSIONS`, or any other Flight function.

## Related

- [`MD_LIST_FLIGHTS`](../md-list-flights) — List remaining Flights.
- [`delete_flight` MCP tool](/sql-reference/mcp/) — AI-agent equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-get-flight

# MD_GET_FLIGHT
> Fetch the summary metadata for a single Flight.
Returns the `FlightSummary` fields for a single [Flight](/concepts/flights). For version-specific content (source code, requirements, config), use [`MD_GET_FLIGHT_VERSION`](../md-get-flight-version).

Users can fetch Flights they have created. [Admins](/concepts/roles-and-access-control/) can fetch Flights they own as well as any Flight in the organization.
## Syntax

```sql
SELECT * FROM MD_GET_FLIGHT(flight_id := '<flight_id>');
```

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `flight_id` | `UUID` | Yes | Identifier of the Flight. |

## Return columns

| Column | Type | Description |
|---|---|---|
| `flight_id` | `UUID` | The Flight identifier. |
| `flight_name` | `VARCHAR` | The current name. |
| `schedule_cron` | `VARCHAR` | The current cron expression, or `NULL` for on-demand only. |
| `schedule_status` | `VARCHAR` | Schedule state (for example, `SCHEDULE_STATUS_ACTIVE` or `SCHEDULE_STATUS_DISABLED`), or `NULL` when the Flight has no schedule. |
| `status` | `VARCHAR` | Flight status (for example, `JOB_STATUS_ACTIVE`). Not the schedule state — see `schedule_status`. |
| `current_version` | `UINTEGER` | The latest version number. |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | Creation timestamp. |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | Last update timestamp. |
| `owner_name` | `VARCHAR` | The user who owns the Flight. |

## Examples

```sql
SELECT flight_id, flight_name, schedule_cron, current_version
FROM MD_GET_FLIGHT(flight_id := '80000000-0000-0000-0000-000000000001');
```

## Related

- [`MD_LIST_FLIGHTS`](../md-list-flights) — List all Flights.
- [`MD_GET_FLIGHT_VERSION`](../md-get-flight-version) — Fetch a specific version's content.
- [`get_flight` MCP tool](/sql-reference/mcp/) — AI-agent equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-get-flight-version

# MD_GET_FLIGHT_VERSION
> Fetch the full content (source, requirements, config, token, secrets) for a specific Flight version.
Returns the full content of a single `FlightVersion`. Use this when you need the source code or requirements that ran for a specific historical run.

## Syntax

```sql
SELECT * FROM MD_GET_FLIGHT_VERSION(
    flight_id := '<flight_id>',
    version_number := <n>
);
```

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `flight_id` | `UUID` | Yes | Identifier of the Flight. |
| `version_number` | `UINTEGER` | Yes | The version to fetch. Version numbers start at `1` and increment on each content update. |

## Return columns

| Column | Type | Description |
|---|---|---|
| `version_id` | `UUID` | Identifier of this version. |
| `flight_id` | `UUID` | Flight identifier. |
| `flight_version` | `UINTEGER` | The version number. |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When this version was created. |
| `access_token_name` | `VARCHAR` | The access token label as of this version. |
| `flight_secret_names` | `VARCHAR[]` | The secret names list as of this version. |
| `config` | `MAP(VARCHAR, VARCHAR)` | The config map as of this version. |
| `source_code` | `VARCHAR` | The Python source as of this version. |
| `requirements_txt` | `VARCHAR` | The `requirements.txt` contents as of this version. |
| `max_runtime_sec` | `UINTEGER` | Per-run timeout in seconds. `0` means no timeout. |

## Behavior

Content fields that are not patched in an update **carry forward** from the previous version. For example, a `source_code`-only update on version 2 produces a version 3 where `requirements_txt`, `config`, `access_token_name`, and `flight_secret_names` match version 2 but `source_code` is the new value.

## Examples

```sql
SELECT flight_version, source_code, requirements_txt
FROM MD_GET_FLIGHT_VERSION(
    flight_id := '80000000-0000-0000-0000-000000000001',
    version_number := 1
);
```

Cross-reference a run's version to read the exact source it executed:

```sql
WITH r AS (
    SELECT flight_version
    FROM MD_LIST_FLIGHT_RUNS(flight_id := '<flight_id>')
    WHERE run_number = <n>
)
SELECT v.source_code, v.requirements_txt
FROM r, MD_GET_FLIGHT_VERSION(flight_id := '<flight_id>', version_number := r.flight_version) v;
```

## Related

- [`MD_LIST_FLIGHT_VERSIONS`](../md-list-flight-versions) — List all versions for a Flight.
- [`MD_GET_FLIGHT`](../md-get-flight) — Fetch current summary metadata only.
- [`get_flight` MCP tool](/sql-reference/mcp/) — AI-agent equivalent (pass a `version` argument).

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-list-flights

# MD_LIST_FLIGHTS
> List Flights with summary metadata.
Returns the summary metadata for every [Flight](/concepts/flights) the caller can see: Users can see Flights they have created. [Admins](/concepts/roles-and-access-control/) can see Flights they own as well as any Flight in the organization. Use the optional `LIMIT` and `OFFSET` parameters to page through large result sets.

## Syntax

```sql
SELECT * FROM MD_LIST_FLIGHTS(
    "LIMIT" := <n>,
    "OFFSET" := <n>,
    owner_only := <boolean>
);
```

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `LIMIT` | `UINTEGER` | No | `50` | Maximum number of Flights to return. |
| `OFFSET` | `UINTEGER` | No | `0` | Skip this many Flights before returning. |
| `owner_only` | `BOOLEAN` | No | `false` | Return only the Flights you own. Meaningful for Admins, who otherwise see the whole organization; for other users the result is the same either way. |

`LIMIT` and `OFFSET` collide with SQL keywords and must be quoted with double quotes when passed as named arguments.

## Return columns

| Column | Type | Description |
|---|---|---|
| `flight_id` | `UUID` | Flight identifier. |
| `flight_name` | `VARCHAR` | The Flight name. |
| `schedule_cron` | `VARCHAR` | Cron expression, or `NULL` for on-demand. |
| `schedule_status` | `VARCHAR` | Schedule state (for example, `SCHEDULE_STATUS_ACTIVE` or `SCHEDULE_STATUS_DISABLED`), or `NULL` when the Flight has no schedule. |
| `status` | `VARCHAR` | Flight status (for example, `JOB_STATUS_ACTIVE`). Not the schedule state — see `schedule_status`. |
| `current_version` | `UINTEGER` | Latest version number. |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | Creation timestamp. |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | Last update timestamp. |
| `owner_name` | `VARCHAR` | The user who owns the Flight. |

Version-specific content (`source_code`, `requirements_txt`, `config`) is not on this row; query [`MD_GET_FLIGHT_VERSION`](../md-get-flight-version) when you need it.

:::note
The name column is `flight_name`, not `name`. Filter and project with `flight_name` (for example, `WHERE flight_name = 'hourly_metrics'`).
:::

## Examples

List all Flights:

```sql
SELECT flight_id, flight_name, schedule_cron, current_version
FROM MD_LIST_FLIGHTS();
```

Page through results:

```sql
SELECT flight_name
FROM MD_LIST_FLIGHTS("LIMIT" := 50, "OFFSET" := 100);
```

Find Flights with active schedules:

```sql
SELECT flight_name, schedule_cron
FROM MD_LIST_FLIGHTS()
WHERE schedule_cron IS NOT NULL;
```

As an Admin, group the organization's Flights by owner:

```sql
SELECT owner_name, count(*) AS flights
FROM MD_LIST_FLIGHTS()
GROUP BY owner_name
ORDER BY flights DESC;
```

Narrow the listing back to the Flights you own:

```sql
SELECT flight_name
FROM MD_LIST_FLIGHTS(owner_only := true);
```

## Related

- [`MD_GET_FLIGHT`](../md-get-flight) — Fetch a single Flight's summary.
- [`MD_LIST_FLIGHT_RUNS`](../md-list-flight-runs) — List a Flight's runs.
- [`list_flights` MCP tool](/sql-reference/mcp/) — AI-agent equivalent (supports a `keywords` filter).

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-list-flight-versions

# MD_LIST_FLIGHT_VERSIONS
> List the version history of a Flight.
Returns every `FlightVersion` for a single [Flight](/concepts/flights), newest first. Use this to browse the history of config, token, secrets, and timeout changes.

Rows carry version metadata only. The source columns (`source_code`, `requirements_txt`) are not returned, so listing a long history doesn't pull a Python file per row — read those for one version with [`MD_GET_FLIGHT_VERSION`](../md-get-flight-version).

## Syntax

```sql
SELECT * FROM MD_LIST_FLIGHT_VERSIONS(
    flight_id := '<flight_id>',
    "LIMIT" := <n>,
    "OFFSET" := <n>
);
```

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `flight_id` | `UUID` | Yes | | Identifier of the Flight. |
| `LIMIT` | `UINTEGER` | No | `50` | Maximum number of versions to return. |
| `OFFSET` | `UINTEGER` | No | `0` | Skip this many versions before returning. |

`LIMIT` and `OFFSET` are SQL keywords and must be quoted when used as named arguments.

## Return columns

| Column | Type | Description |
|---|---|---|
| `version_id` | `UUID` | Identifier of this version. |
| `flight_id` | `UUID` | Flight identifier. |
| `flight_version` | `UINTEGER` | Version number, newest first. |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When this version was created. |
| `access_token_name` | `VARCHAR` | Access token label for this version. |
| `flight_secret_names` | `VARCHAR[]` | Secret names list for this version. |
| `config` | `MAP(VARCHAR, VARCHAR)` | Config map for this version. |
| `max_runtime_sec` | `UINTEGER` | Per-run timeout in seconds. `0` means no timeout. |

## Examples

Get the full version history:

```sql
SELECT flight_version, created_at, access_token_name
FROM MD_LIST_FLIGHT_VERSIONS(flight_id := '<flight_id>');
```

Just the latest version:

```sql
SELECT flight_version, created_at
FROM MD_LIST_FLIGHT_VERSIONS(flight_id := '<flight_id>', "LIMIT" := 1);
```

Skip the latest, get the rest:

```sql
SELECT flight_version, created_at
FROM MD_LIST_FLIGHT_VERSIONS(flight_id := '<flight_id>', "OFFSET" := 1);
```

Find which versions changed the per-run timeout:

```sql
SELECT flight_version, created_at, max_runtime_sec
FROM MD_LIST_FLIGHT_VERSIONS(flight_id := '<flight_id>');
```

## Related

- [`MD_GET_FLIGHT_VERSION`](../md-get-flight-version) — Fetch a single version by number.
- [`MD_LIST_FLIGHT_RUNS`](../md-list-flight-runs) — Each run row includes the `flight_version` it used.
- [`list_flight_versions` MCP tool](/sql-reference/mcp/) — AI-agent equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-run-flight

# MD_RUN_FLIGHT
> Trigger an on-demand execution of a Flight using its current version.
Triggers a new run of a [Flight](/concepts/flights) using the Flight's current version. The run is asynchronous: `MD_RUN_FLIGHT` returns immediately with a `RUN_STATUS_RUNNING` (or `RUN_STATUS_PENDING`) row. Use [`MD_LIST_FLIGHT_RUNS`](../md-list-flight-runs) to poll for completion and [`MD_GET_FLIGHT_LOGS`](../md-get-flight-logs) to read the output.

## Syntax

```sql
SELECT * FROM MD_RUN_FLIGHT(flight_id := '<flight_id>');
```

`MD_RUN_FLIGHT` is a table function; you can also call it with `CALL` when you don't need the result row:

```sql
CALL MD_RUN_FLIGHT(flight_id := '<flight_id>');
```

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `flight_id` | `UUID` | Yes | Identifier of the Flight to run. |
| `config` | `MAP(VARCHAR, VARCHAR)` | No | Per-run config overrides. Only keys already defined on the Flight can be set; keys you omit keep their stored values. The override applies to this run only and leaves the stored config and version untouched. |

## Return columns

| Column | Type | Description |
|---|---|---|
| `run_id` | `UUID` | Unique identifier of the new run. |
| `flight_id` | `UUID` | The Flight identifier. |
| `flight_name` | `VARCHAR` | The Flight name. |
| `flight_version` | `UINTEGER` | The version this run locked to. |
| `config` | `MAP(VARCHAR, VARCHAR)` | The effective config for this run: the stored config with any per-run overrides applied. |
| `run_number` | `UBIGINT` | Sequential run number assigned to this run. |
| `is_scheduled` | `BOOLEAN` | `false` for on-demand runs. |
| `status` | `VARCHAR` | Initial run status (`RUN_STATUS_PENDING` or `RUN_STATUS_RUNNING`). |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When the run was created. |
| `started_at` | `TIMESTAMP WITH TIME ZONE` | When the run started executing. `NULL` until it starts. |
| `ended_at` | `TIMESTAMP WITH TIME ZONE` | When the run finished. `NULL` for a run that is still pending or running. |
| `scheduled_at` | `TIMESTAMP WITH TIME ZONE` | When the run was scheduled. |
| `cancelled_at` | `TIMESTAMP WITH TIME ZONE` | When the run was cancelled, or `NULL`. |
| `exit_code` | `INTEGER` | Process exit code. `NULL` until the run finishes; `0` means success. |

The row is the same run record returned by [`MD_LIST_FLIGHT_RUNS`](../md-list-flight-runs); the timing columns (`started_at`, `ended_at`, `cancelled_at`) and `exit_code` are still `NULL` when `MD_RUN_FLIGHT` returns.

## Behavior

- The new run locks to the Flight's current version. Subsequent updates to the Flight do not affect this run.
- The run number is assigned sequentially per Flight and visible through [`MD_LIST_FLIGHT_RUNS`](../md-list-flight-runs).
- Multiple concurrent runs of the same Flight are allowed; each gets its own run number.
- A `config` argument overrides stored config values for this run only. You can override only keys the Flight already defines; it can't add new keys. The config a run used is recorded in the `config` column of [`MD_LIST_FLIGHT_RUNS`](../md-list-flight-runs).

## Examples

Trigger a run and capture the row:

```sql
SELECT flight_version, status
FROM MD_RUN_FLIGHT(flight_id := '80000000-0000-0000-0000-000000000001');
```

Trigger and then poll until the run finishes:

```sql
-- Kick off the run
CALL MD_RUN_FLIGHT(flight_id := '<flight_id>');

-- Poll the latest run's status
SELECT run_number, status
FROM MD_LIST_FLIGHT_RUNS(flight_id := '<flight_id>')
ORDER BY run_number DESC
LIMIT 1;
```

Override a config value for a single run:

```sql
CALL MD_RUN_FLIGHT(
    flight_id := '<flight_id>',
    config := MAP {'REGION': 'eu-central-1'}
);
```

## Related

- [`MD_LIST_FLIGHT_RUNS`](../md-list-flight-runs) — List runs for a Flight.
- [`MD_GET_FLIGHT_LOGS`](../md-get-flight-logs) — Read combined stdout/stderr for a run.
- [`MD_CANCEL_FLIGHT_RUN`](../md-cancel-flight-run) — Cancel an in-progress run.
- [`run_flight` MCP tool](/sql-reference/mcp/) — AI-agent equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-list-flight-runs

# MD_LIST_FLIGHT_RUNS
> List the execution history of a Flight, newest first.
Returns every run of a single [Flight](/concepts/flights). Each row has a status, a sequential run number, and the version of the Flight that ran.

## Syntax

```sql
SELECT * FROM MD_LIST_FLIGHT_RUNS(
    flight_id := '<flight_id>',
    "LIMIT" := <n>,
    "OFFSET" := <n>
);
```

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `flight_id` | `UUID` | Yes | | Identifier of the Flight. |
| `LIMIT` | `UINTEGER` | No | `50` | Maximum number of runs to return. |
| `OFFSET` | `UINTEGER` | No | `0` | Skip this many runs before returning. |

`LIMIT` and `OFFSET` are SQL keywords and must be quoted when used as named arguments.

## Return columns

| Column | Type | Description |
|---|---|---|
| `run_id` | `UUID` | Unique identifier of the run. |
| `flight_id` | `UUID` | Flight identifier. |
| `flight_name` | `VARCHAR` | Flight name at the time of the run. |
| `flight_version` | `UINTEGER` | The version this run locked to at start. |
| `config` | `MAP(VARCHAR, VARCHAR)` | The config the run used, including any [per-run overrides](../md-run-flight) passed to `MD_RUN_FLIGHT`. |
| `run_number` | `UBIGINT` | Sequential run number, starting at `1`. |
| `is_scheduled` | `BOOLEAN` | `true` if the run was triggered by the schedule, `false` for on-demand. |
| `status` | `VARCHAR` | Run status: `RUN_STATUS_PENDING`, `RUN_STATUS_RUNNING`, `RUN_STATUS_SUCCEEDED`, `RUN_STATUS_FAILED`, or `RUN_STATUS_CANCELLED`. |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When the run was created. |
| `started_at` | `TIMESTAMP WITH TIME ZONE` | When the run started executing, or `NULL` if it hasn't started. |
| `ended_at` | `TIMESTAMP WITH TIME ZONE` | When the run finished, or `NULL` while it's still running. |
| `scheduled_at` | `TIMESTAMP WITH TIME ZONE` | When the run was scheduled. |
| `cancelled_at` | `TIMESTAMP WITH TIME ZONE` | When the run was cancelled, or `NULL`. |
| `exit_code` | `INTEGER` | Process exit code, or `NULL` while the run is in progress. `0` means success. |

A Flight created before per-run config overrides shipped may report empty strings for `config` until you update the Flight once, which redeploys it.

## Examples

Latest 10 runs, newest first, with the config each run used:

```sql
SELECT run_number, status, flight_version, config, created_at
FROM MD_LIST_FLIGHT_RUNS(flight_id := '<flight_id>')
ORDER BY run_number DESC
LIMIT 10;
```

Find recent failures:

```sql
SELECT run_number, flight_version, created_at
FROM MD_LIST_FLIGHT_RUNS(flight_id := '<flight_id>')
WHERE status = 'RUN_STATUS_FAILED'
ORDER BY run_number DESC;
```

Total runs per version:

```sql
SELECT flight_version, COUNT(*) AS runs
FROM MD_LIST_FLIGHT_RUNS(flight_id := '<flight_id>')
GROUP BY flight_version
ORDER BY flight_version DESC;
```

## Related

- [`MD_RUN_FLIGHT`](../md-run-flight) — Trigger an on-demand run.
- [`MD_GET_FLIGHT_LOGS`](../md-get-flight-logs) — Read a specific run's output.
- [`MD_CANCEL_FLIGHT_RUN`](../md-cancel-flight-run) — Cancel an in-progress run.
- [`list_flight_runs` MCP tool](/sql-reference/mcp/) — AI-agent equivalent.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-get-flight-logs

# MD_GET_FLIGHT_LOGS
> Read the combined stdout and stderr captured during a Flight run.
Returns the captured logs for a single [Flight](/concepts/flights) run. The output combines stdout and stderr in the order the runtime captured them.

## Syntax

```sql
SELECT logs FROM MD_GET_FLIGHT_LOGS(
    flight_id := '<flight_id>',
    run_number := <n>
);
```

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `flight_id` | `UUID` | Yes | Identifier of the Flight. |
| `run_number` | `UBIGINT` | Yes | The run number to fetch logs for. |

## Return columns

| Column | Type | Description |
|---|---|---|
| `logs` | `VARCHAR` | The full combined stdout/stderr captured during the run. |

## Behavior

- Returns an error when no run with the given `run_number` exists for the Flight, or when the Flight itself doesn't exist.
- Available for runs in any terminal status (`SUCCEEDED`, `FAILED`, `CANCELLED`) and during a `RUNNING` run.
- Parameters must be literals or `getvariable()` calls. Subqueries and lateral join columns fail with a binder error; store dynamic values with `SET VARIABLE` first.
- Pass arguments by name. The signature order is `MD_GET_FLIGHT_LOGS(flight_id, run_number)` — `flight_id` first, then `run_number`.

## Examples

Read the latest run's logs:

```sql
SET VARIABLE latest_run_number = (
    SELECT max(run_number)
    FROM MD_LIST_FLIGHT_RUNS(flight_id := '<flight_id>')
);

SELECT logs
FROM MD_GET_FLIGHT_LOGS(
    flight_id := '<flight_id>',
    run_number := getvariable('latest_run_number')
);
```

Read a specific run:

```sql
SELECT logs
FROM MD_GET_FLIGHT_LOGS(
    flight_id := '80000000-0000-0000-0000-000000000001',
    run_number := 42
);
```

## Related

- [`MD_LIST_FLIGHT_RUNS`](../md-list-flight-runs) — Find the run number to read logs for.
- [`MD_RUN_FLIGHT`](../md-run-flight) — Trigger an on-demand run.
- [`get_flight_run_logs` MCP tool](/sql-reference/mcp/) — AI-agent equivalent, with a `max_bytes` cap.

---

Source: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/md-cancel-flight-run

# MD_CANCEL_FLIGHT_RUN
> Cancel an in-progress Flight run.
Cancels an in-progress run of a [Flight](/concepts/flights). The run transitions to `RUN_STATUS_CANCELLED`.

Cancelling a run that's already in a terminal status (`SUCCEEDED`, `FAILED`, `CANCELLED`) or a run that doesn't exist returns an error.

## Syntax

```sql
CALL MD_CANCEL_FLIGHT_RUN(
    flight_id := '<flight_id>',
    run_number := <n>
);
```

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `flight_id` | `UUID` | Yes | Identifier of the Flight. |
| `run_number` | `UBIGINT` | Yes | The run number to cancel. |

## Examples

Cancel the most recent run if it's still in progress:

```sql
WITH latest AS (
    SELECT run_number, status
    FROM MD_LIST_FLIGHT_RUNS(flight_id := '<flight_id>')
    ORDER BY run_number DESC LIMIT 1
)
SELECT MD_CANCEL_FLIGHT_RUN(flight_id := '<flight_id>', run_number := latest.run_number)
FROM latest
WHERE latest.status IN ('RUN_STATUS_PENDING', 'RUN_STATUS_RUNNING');
```

Cancel a specific run:

```sql
CALL MD_CANCEL_FLIGHT_RUN(
    flight_id := '80000000-0000-0000-0000-000000000001',
    run_number := 42
);
```

## Related

- [`MD_LIST_FLIGHT_RUNS`](../md-list-flight-runs) — Find runs that are still in progress.
- [`MD_RUN_FLIGHT`](../md-run-flight) — Trigger an on-demand run.
- [`cancel_flight_run` MCP tool](/sql-reference/mcp/) — AI-agent equivalent.

---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fmotherduck-sql-reference%2Fflights%2F&page_title=MotherDuck%20Documentation%20-%20Flights&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.