Backfill permissions

A backfill reruns a Dag for a historical date range. On Astro Private Cloud (APC), the APC API issues a JWT for each user when they access the Airflow UI or API. The JWT carries the user’s mapped Airflow role and the corresponding permissions. Airflow enforces backfill access against those permissions. This page describes the APC-specific role mapping and how to grant, revoke, and audit backfill access. For general Airflow concepts, CLI flags, and UI behavior, see the related Astronomer Learn guides:

For general user role assignment outside the backfill scope, see Manage users on Astro Private Cloud and the User roles and permissions reference.

Permission model

APC API deployment role to Airflow role

When a user opens the Airflow UI or API for a Deployment, the APC API maps the user’s deployment-level role to an Airflow role and encodes the matching permission set in the JWT.

APC API role	Airflow role	Backfill access
`DEPLOYMENT_VIEWER`	Viewer	`read`
`DEPLOYMENT_EDITOR`	User	`read`, `create`, `edit`, `delete`
`DEPLOYMENT_ADMIN`	Admin	`read`, `create`, `edit`, `delete`

A user with WORKSPACE_ADMIN on the parent Workspace, or SYSTEM_ADMIN at the system level, inherits Admin-equivalent backfill access on every Deployment in scope. You don’t need to grant a deployment-level role on top.

Backfill actions

The backfill resource supports four actions.

Action	Description
`read`	View backfill status and history
`create`	Create new backfills
`edit`	Modify an existing backfill, such as pausing or resuming it
`delete`	Cancel a backfill

How permission changes propagate

The APC API issues a JWT when the user accesses the Airflow UI. The JWT lifetime is controlled by the jwt.authDuration APC config and defaults to 24 hours. A role change takes effect when the APC API issues a new JWT, typically on the user’s next sign-in or token refresh. Until then, the existing JWT continues to grant the previous permissions, so a role change can take up to 24 hours to reach an active session. To force the change immediately, have the user sign out and sign back in.

Prerequisites

The user has DEPLOYMENT_EDITOR or DEPLOYMENT_ADMIN on the target Deployment, or an inherited role from the Workspace or system level.
The Dag exists and is unpaused.
The target date range is valid for the Dag’s schedule.

Trigger a backfill

The trigger mechanism depends on the Airflow version running in your Deployment.

Airflow 2.x
Airflow 3.x

Airflow 2 doesn’t expose a backfill action in the UI. Use the Airflow CLI from a machine that can reach the Deployment.

airflow dags backfill \
  --start-date 2026-01-01 \
  --end-date 2026-01-31 \
  --reset-dagruns \
  <dag-id>

The --reset-dagruns flag deletes existing backfill-related Dag runs in the range and starts a fresh set. To rerun only failed tasks instead, use --rerun-failed-tasks. For a walkthrough with examples, see Rerun Airflow Dags and tasks.

You can trigger an Airflow 3 backfill from the UI, the CLI, or the REST API.Use the Airflow UI

Open the Dag's details

Navigate to the Dag in the Airflow UI and open its details page.

Trigger a backfill

Click Trigger, then select Backfill in the dialog.

Configure the run

Set the start date, end date, and reprocessing behavior, then submit.

Use the Airflow CLI

airflow backfill create \
  --dag-id <dag-id> \
  --from-date 2026-01-01 \
  --to-date 2026-01-31 \
  --reprocess-behavior failed

The --reprocess-behavior flag accepts none, failed, or completed. For a walkthrough with examples, see Rerun Airflow Dags and tasks.Use the Airflow REST API

curl -X POST \
  "https://<deployment-url>/api/v2/backfills" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "dag_id": "<dag-id>",
    "from_date": "2026-01-01T00:00:00Z",
    "to_date": "2026-01-31T00:00:00Z",
    "reprocess_behavior": "failed"
  }'

This endpoint requires backfill.create, which DEPLOYMENT_EDITOR and DEPLOYMENT_ADMIN provide. For automated backfills triggered by CI or scheduled jobs, use a Deployment service account with DEPLOYMENT_EDITOR rather than a personal user token.

Manage backfill access

Backfill access uses the standard APC role-assignment flow. For the full reference, see Manage users on Astro Private Cloud. The examples in this section show the calls scoped to backfill use cases.

Grant or change a role

APC API
Astro CLI

Use the deploymentAddUserRole GraphQL mutation to add a user, or deploymentUpdateUserRole to change an existing user’s role.

mutation {
  deploymentAddUserRole(
    deploymentId: "<deployment-id>"
    email: "<user-email>"
    role: DEPLOYMENT_EDITOR
  ) {
    id
  }
}

Use role: DEPLOYMENT_VIEWER to restrict a user to read-only access instead.

astro deployment user add \
  --deployment-id=<deployment-id> \
  --email=<user-email> \
  --role=DEPLOYMENT_EDITOR

To change an existing user’s role, use astro deployment user update with --deployment-id and --role.

Restrict to read-only access

Use the same APC API or Astro CLI commands with role: DEPLOYMENT_VIEWER (or --role=DEPLOYMENT_VIEWER). The user can view backfill status and history but can’t create, modify, or cancel backfills.

Revoke access

To remove a user from the Deployment entirely, use the APC deploymentRemoveUserRole mutation or astro deployment user remove.

APC API
Astro CLI

Use the deploymentRemoveUserRole mutation to remove a user from a Deployment entirely:

mutation {
  deploymentRemoveUserRole(
    deploymentId: "<deployment-id>"
    email: "<user-email>"
  ) {
    id
  }
}

After the role binding is removed, the user retains their previous access until their JWT expires (up to 24 hours by default).

astro deployment user remove \
  --deployment-id=<deployment-id> \
  --email=<user-email>

After the role binding is removed, the user retains their previous backfill capabilities until their JWT expires. See How permission changes propagate.

Monitor backfills

Use the Airflow UI

Backfill runs appear in the Dag’s run list with a backfill run-type label, alongside scheduled and manually triggered runs.

Query the metadata database

Backfill Dag runs are stored in the dag_run table with run_type = 'backfill'.

SELECT dag_id, run_type, state, start_date, end_date
FROM dag_run
WHERE run_type = 'backfill'
ORDER BY start_date DESC;

Direct access to the metadata database is typically restricted to platform operators on APC. If you don’t have direct access, use the Airflow UI or the Airflow REST API instead.

Troubleshoot

Access denied when creating a backfill

The user has DEPLOYMENT_VIEWER, which only grants backfill.read. Promote them with deploymentUpdateUserRole: Use the deploymentUpdateUserRole mutation to change an existing user’s role on a Deployment, for example to promote a DEPLOYMENT_VIEWER to DEPLOYMENT_EDITOR:

mutation {
  deploymentUpdateUserRole(
    deploymentId: "<deployment-id>"
    email: "<user-email>"
    role: DEPLOYMENT_EDITOR
  ) {
    id
  }
}

Backfills aren’t visible to a user

The user has no role on the Deployment. Add them with at least DEPLOYMENT_VIEWER. If the user holds WORKSPACE_VIEWER and still can’t see the Deployment, confirm the Deployment is in the same Workspace.

A role change hasn’t taken effect

The user is still presenting their existing JWT, which keeps the previous permissions until it expires. The default JWT lifetime is 24 hours. Have the user sign out and sign back in to force APC to issue a fresh token. If they authenticate through SSO, ensure the IdP session is also refreshed.

Best practices

Assign DEPLOYMENT_EDITOR to operators who run backfills regularly. Reserve DEPLOYMENT_ADMIN for users who also manage Deployment configuration.
Assign DEPLOYMENT_VIEWER to stakeholders who only need to monitor Dag runs.
Use a Deployment service account with DEPLOYMENT_EDITOR for automated backfills triggered from CI or scheduled jobs, rather than a personal user token.
Audit backfill activity by querying dag_run.run_type = 'backfill' or by reviewing the Dag’s run list.
Test large historical backfills in a non-production Deployment first.
Set worker concurrency and Dag-level max_active_runs to limit the load a backfill places on the Deployment.

Overview

Architecture

Upgrade to Astro Private Cloud 2.0

Install Astro Private Cloud

Develop Dags

Airflow administration

Airflow 3

Deploy Dags

Manage Deployments

Platform administration

Manage Platform resources

Security and compliance

APC API

Platform Observability

Release notes

Reference

Backfill permissions

Permission model

APC API deployment role to Airflow role

Backfill actions

How permission changes propagate

Prerequisites

Trigger a backfill

Manage backfill access

Grant or change a role

Restrict to read-only access

Revoke access

Monitor backfills

Use the Airflow UI

Query the metadata database

Troubleshoot

Access denied when creating a backfill

Backfills aren’t visible to a user

A role change hasn’t taken effect

Best practices

​Permission model

​APC API deployment role to Airflow role

​Backfill actions

​How permission changes propagate

​Prerequisites

​Trigger a backfill

​Manage backfill access

​Grant or change a role

​Restrict to read-only access

​Revoke access

​Monitor backfills

​Use the Airflow UI

​Query the metadata database

​Troubleshoot

​Access denied when creating a backfill

​Backfills aren’t visible to a user

​A role change hasn’t taken effect

​Best practices

Permission model

APC API deployment role to Airflow role

Backfill actions

How permission changes propagate

Prerequisites

Trigger a backfill

Manage backfill access

Grant or change a role

Restrict to read-only access

Revoke access

Monitor backfills

Use the Airflow UI

Query the metadata database

Troubleshoot

Access denied when creating a backfill

Backfills aren’t visible to a user

A role change hasn’t taken effect

Best practices