> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Using the Airflow REST API with Astro
For Deployments on Astro, you can use the Airflow [REST API](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html) to automate Airflow workflows. For example, you can externally trigger a dag run without accessing your Deployment directly by making an HTTP request in Python or cURL to the [dagRuns endpoint](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html#operation/post_dag_run) in the Airflow REST API.
To test Airflow API calls in a local Airflow environment running with the Astro CLI, see [Troubleshoot your local Airflow environment](/docs/cli/v1.43/run-airflow-locally).
Updates to the Airflow REST API are released in new Airflow versions and new releases don’t have a separate release cycle or versioning scheme. To take advantage of specific Airflow REST API functionality, you might need to upgrade Astro Runtime. See [Upgrade Runtime](/docs/runtime/upgrade-astro-runtime) and the [Airflow release notes](https://airflow.apache.org/docs/apache-airflow/stable/release_notes.html).
**Airflow REST API v2 (Airflow 3.0+)**
The Airflow REST API is available at `/api/v2` for Airflow 3.0 and above. Some endpoints and parameters have changed. See the [Airflow API](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html) documentation for more information.
## Prerequisites
* A Deployment on Astro.
* A [Deployment API token](/docs/astro/deployment-api-tokens), [Workspace API token](/docs/astro/workspace-api-tokens), or an [Organization API token](/docs/astro/organization-api-tokens).
* [cURL](https://curl.se/) or, if using Python, the [Requests library](https://docs.python-requests.org/en/latest/index.html).
* The [Astro CLI](/docs/cli/v1.43/overview).
## Step 1: Retrieve your access token
Follow the steps in [Create a Workspace API token](/docs/astro/workspace-api-tokens#create-a-workspace-api-token) to create your token. Make sure to save the token on creation in order to use it later in this setup.
Follow the steps in [Create a Organization API token](/docs/astro/organization-api-tokens#create-an-organization-api-token) to create your token. Make sure to save the token on creation in order to use it later in this setup.
Follow the steps in [Create a Deployment API token](/docs/astro/deployment-api-tokens#create-a-deployment-api-token) to create your token. Make sure to save the token on creation in order to use it later in this setup.
## Step 2: Retrieve the Deployment URL
Your Deployment URL is the [host](https://swagger.io/docs/specification/2-0/api-host-and-base-path/) you use to call the Airflow API.
1. Run the following command to retrieve the URL for your Deployment Airflow UI:
```sh wrap theme={null}
astro deployment inspect -n --key metadata.airflow_api_url
```
Alternatively, you can retrieve your Deployment URL by opening the Airflow UI for your Deployment on Astro and copying the URL of the page up to `/home`. For example, if the home page of your Deployment Airflow UI is hosted at `clq52c95r000208i8c7wahwxt.astronomer.run/dz3uu847/home`, your Deployment URL is `clq52c95r000208i8c7wahwxt.astronomer.run/dz3uu847`.
## Step 3: Make an Airflow API request
You can execute requests against any endpoint that is listed in the [Airflow REST API reference](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html).
To make a request based on Airflow documentation, make sure to:
* Use the Astro access token from Step 1 for authentication.
* Replace `airflow.apache.org` with your Deployment URL from Step 1.
The Airflow REST API doesn't have rate-limiting.
## Example API Requests
The following are common examples of Airflow REST API requests that you can run against a Deployment on Astro.
### List Dags
To retrieve a list of all Dags in a Deployment, you can run a `GET` request to the [`dags` endpoint](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html#operation/get_dags)
#### cURL
```sh wrap theme={null}
curl -X GET https:///api/v2/dags \
-H 'Authorization: Bearer '
```
#### Python
```python wrap theme={null}
import requests
token = ""
deployment_url = ""
response = requests.get(
url=f"https://{deployment_url}/api/v2/dags",
headers={"Authorization": f"Bearer {token}"}
)
print(response.json())
# Prints data about all dags in your Deployment
```
### Trigger a Dag run
You can trigger a Dag run by executing a `POST` request to Airflow's [`dagRuns` endpoint](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html#operation/post_dag_run).
This will trigger a Dag run for the Dag you specify, which is equivalent to clicking the **Play** button in the main **Dags** view of the Airflow UI. The request body must include the `logical_date` key — it can be `null`, which runs the Dag immediately, but it can't be omitted. An empty body `{}` returns a `422 Unprocessable Entity` error.
#### cURL
```sh wrap theme={null}
curl -X POST https:///api/v2/dags//dagRuns \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{"logical_date": null}'
```
#### Python
```python wrap theme={null}
import requests
token = ""
deployment_url = ""
dag_id = ""
response = requests.post(
url=f"https://{deployment_url}/api/v2/dags/{dag_id}/dagRuns",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
},
data='{"logical_date": null}'
)
print(response.json())
# Prints metadata of the dag run that was just triggered
```
### Trigger a Dag run by date
You can also specify a `logical_date` at the time in which you wish to trigger the Dag run by passing the `logical_date` with the desired timestamp with the request's `data` field. The timestamp string is expressed in UTC and must be specified in the format `"YYYY-MM-DDTHH:MM:SSZ"`, where:
* `YYYY` represents the year.
* `MM` represents the month.
* `DD` represents the day.
* `HH` represents the hour.
* `MM` represents the minute.
* `SS` represents the second.
* `Z` stands for "Zulu" time, which represents UTC.
#### cURL
```sh wrap theme={null}
curl -v -X POST https:///api/v2/dags//dagRuns \
-H 'Authorization: Bearer ' \
-H 'content-type: application/json' \
-d '{"logical_date":"2022-11-16T11:34:00Z"}'
```
#### Python
Using Python:
```python wrap theme={null}
import requests
token = ""
deployment_url = ""
dag_id = ""
response = requests.post(
url=f"https://{deployment_url}/api/v2/dags/{dag_id}/dagRuns",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
},
data='{"logical_date": "2021-11-16T11:34:01Z"}'
)
print(response.json())
# Prints metadata of the dag run that was just triggered
```
### Pause a Dag
You can pause a Dag by executing a `PATCH` command against the [`dag` endpoint](https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html#operation/patch_dag).
Replace `` with your own value.
#### cURL
```sh wrap theme={null}
curl -X PATCH https:///api/v2/dags/ \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{"is_paused": true}'
```
#### Python
```python wrap theme={null}
import requests
token = ""
deployment_url = ""
dag_id = ""
response = requests.patch(
url=f"https://{deployment_url}/api/v2/dags/{dag_id}",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
},
data='{"is_paused": true}'
)
print(response.json())
# Prints data about the dag with id
```
### Trigger Dag runs across Deployments
You can use the Airflow REST API to make a request in one Deployment that triggers a Dag run in a different Deployment. This is sometimes necessary when you have interdependent workflows across multiple Deployments. On Astro, you can do this for any Deployment in any Workspace or cluster.
This topic has guidelines on how to trigger a Dag run, but you can modify the example Dag provided to trigger any request that's supported in the Airflow REST API.
1. Create a [Deployment API token](/docs/astro/deployment-api-tokens) for the Deployment that contains the Dag you want to trigger.
2. In the Deployment that contains the triggering Dag, create an [Airflow HTTP connection](https://airflow.apache.org/docs/apache-airflow-providers-http/stable/connections/http.html) with the following values:
* **Connection Id**: `http_conn`
* **Connection Type**: HTTP
* **Host**: ``
* **Schema**: `https`
* **Extra**:
```json wrap theme={null}
{
"Content-Type": "application/json",
"Authorization": "Bearer "
}
```
See [Manage connections in Apache Airflow](/docs/learn/connections).
If the `HTTP` connection type is not available, double check that the [HTTP provider](https://airflow.apache.org/registry/providers/http/) is installed in your Airflow environment. If it's not, add `apache-airflow-providers-http` to the `requirements.txt` file of our Astro project and redeploy it to Astro.
3. In your triggering Dag, add the following task. It uses the [`HttpOperator`](https://airflow.apache.org/registry/providers/http#http-http-HttpOperator) to make a request to the `dagRuns` endpoint of the Deployment that contains the Dag to trigger.
```python wrap theme={null}
from datetime import datetime
from airflow.models.dag import DAG
from airflow.providers.http.operators.http import HttpOperator
with DAG(
dag_id="triggering_dag",
start_date=datetime(2024, 1, 1),
schedule=None,
):
HttpOperator(
task_id="trigger_external_dag",
log_response=True,
method="POST",
endpoint="api/v2/dags//dagRuns",
http_conn_id="http_conn",
data={
"logical_date": "{{ logical_date }}",
# To pass parameters, add: "params": {"foo": "bar"}
},
)
```