# GRANT RUN ON FLIGHT


> Let users, roles, or your whole organization run a Flight you own, and list or revoke those grants.

Gives users, roles, or your whole organization access to run a [Flight](/concepts/flights) you own, for example so viewers can run it from a button in a [Dive with write-back](/key-tasks/dives/run-flights-from-dives). `REVOKE RUN ON FLIGHT` removes access, and `SHOW GRANTS ON FLIGHT` lists it.

:::note
Only a Flight's owner can grant `run` on it. A run always uses the owner's token, secrets, and settings, whoever starts it, so organization Admins can't grant `run` on Flights they don't own. Admins can list and revoke `run` grants on any Flight in the organization.
:::

## Syntax

```sql
GRANT RUN ON FLIGHT '<flight_id>' TO { USER <username> | ROLE <role_name> | ORGANIZATION } [, ...];

REVOKE RUN ON FLIGHT '<flight_id>' FROM { USER <username> | ROLE <role_name> | ORGANIZATION } [, ...];

SHOW GRANTS ON FLIGHT '<flight_id>';
```

## Parameters

| Parameter | Description |
|---|---|
| `<flight_id>` | The Flight's ID, as a single-quoted string. Flight names aren't accepted. Find IDs with `SELECT flight_id, flight_name FROM MD_LIST_FLIGHTS();`. |
| `USER <username>` | A MotherDuck username, not an email address. Double-quote names that contain special characters, such as `@`. |
| `ROLE <role_name>` | A [role](/concepts/roles-and-access-control/), including the preset `admin`, `builder`, and `explorer` roles. The grant reaches the role's members and anyone holding a role that inherits it. Preset roles nest: Admin is a member of Builder, and Builder of Explorer, so `ROLE explorer` also reaches every Builder and Admin. |
| `ORGANIZATION` | Everyone in your organization, including its service accounts. |

`RUN` is the only permission a Flight supports. Grantees must be typed: a bare name without `USER` or `ROLE` is a syntax error.

## What a `run` grant allows

A grantee can run the Flight, including from a Dive, with [per-run config overrides](/key-tasks/flights/scheduling-and-runs#override-config-for-a-single-run). They can read each run they started, one at a time by run number, with [`MD_GET_FLIGHT_RUN`](../md-get-flight-run): its status, times, exit code, and config values.

A grantee can't list the Flight's runs with [`MD_LIST_FLIGHT_RUNS`](../md-list-flight-runs), read its source or logs, or edit, cancel, or delete it. [Users with no roles](/concepts/roles-and-access-control/#users-with-no-roles) and connections that use a read scaling token can't run Flights, even with a grant, and can't grant `run` either.

## Behavior

- **One statement, all or nothing.** If any grantee doesn't exist, the statement fails and nothing is granted.
- **At most 100 grantees** per statement.
- **Idempotent.** Granting an existing grant or revoking an absent one succeeds and changes nothing.
- **Case-insensitive names.** Usernames, role names, and keywords match regardless of case.
- **Grants follow the Flight.** Deleting a Flight deletes its grants.

## Output of `SHOW GRANTS ON FLIGHT`

| Column | Description |
|---|---|
| `grantee_name` | The username or role name. For an organization grant, the organization's name. |
| `grantee_type` | `user`, `role`, or `organization`. |
| `privilege` | `run`. |

Rows are sorted by `grantee_type`, then `grantee_name`. The same rows are available as a table function, [`MD_LIST_FLIGHT_GRANTEES`](../md-list-flight-grantees), which you can use in joins and subqueries.

## Examples

Let everyone with the `order_approvers` role run a Flight:

```sql
GRANT RUN ON FLIGHT '7b1e2c3d-0000-4000-8000-000000000001' TO ROLE order_approvers;
```

Grant to a user and a role in one statement:

```sql
GRANT RUN ON FLIGHT '7b1e2c3d-0000-4000-8000-000000000001' TO USER duck, ROLE finance;
```

List who can run the Flight:

```sql
SHOW GRANTS ON FLIGHT '7b1e2c3d-0000-4000-8000-000000000001';
```

```text
┌─────────────────┬──────────────┬───────────┐
│  grantee_name   │ grantee_type │ privilege │
├─────────────────┼──────────────┼───────────┤
│ finance         │ role         │ run       │
│ order_approvers │ role         │ run       │
│ duck            │ user         │ run       │
└─────────────────┴──────────────┴───────────┘
```

Remove one grantee and keep the others:

```sql
REVOKE RUN ON FLIGHT '7b1e2c3d-0000-4000-8000-000000000001' FROM USER duck;
```

## Errors

| Error | Cause |
|---|---|
| `Flight id must be a UUID, got '<value>'` | The statement names the Flight rather than its ID. |
| `Could not find Flight` | No Flight with that ID exists in your organization, or you don't own it and aren't an Admin. |
| `Only the owner of this Flight can add grants` | An Admin tried to grant `run` on a Flight they don't own. Admins can only list and revoke. |
| `Permission '<name>' is not supported on a Flight` | A permission other than `RUN`, such as `READ`. |
| `expected USER <name>, ROLE <name> or ORGANIZATION, got <name>` | A grantee without `USER` or `ROLE` in front of it. |
| `Unable to find user <name>` or `Unable to find role <name>` | The grantee doesn't exist. Usernames aren't email addresses. With several unknown names, the error lists them all, such as `Unable to find users alice, bob`. |
| `At most 100 grantees may be changed in one call` | The statement names more than 100 grantees. Split it. |
| `Read-only credentials cannot change grants` | The connection uses a read-only token. |

## Related

- [Add write-back to a Dive](/key-tasks/dives/run-flights-from-dives) — run a Flight from a button in a Dive.
- [`MD_LIST_FLIGHT_GRANTEES`](../md-list-flight-grantees) — the grants as a table function.
- [`grant_access` MCP tool](/sql-reference/mcp/flights/grant-access) — AI-agent equivalent.
- [Roles and access control](/concepts/roles-and-access-control/)


---

## 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%2Fgrant-run-on-flight%2F&page_title=GRANT%20RUN%20ON%20FLIGHT&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.