Example APC API queries

The examples on this page show common ways to use the APC API — they’re not a complete API reference. For the full, interactive API documentation for your installation, including every available query, mutation, and type, go to https://houston.<your-base-domain>/v1, and click on the Docs tab. See Develop and test APC API queries for more on using the built-in GraphQL explorer.

You can retrieve common information for specific Astronomer objects by using the following sample queries.

Find the ID of a workspace you belong to

Use the workspaces query to find the ID of a Workspace that you belong to. Optionally, you can choose to filter by Deployment label.

query {
  workspaces(label:"example-workspace") {
    id,
    label
  }
}

Find the ID of all workspaces

System administrators can use the sysWorkspaces query to perform a bulk-fetch of all Workspaces and their respective IDs using the sysWorkspaces query. After retrieving the full list, you can filter the Workspaces within your application to locate the ID corresponding to the label of interest.

query {
  sysWorkspaces {
    id,
    label
  }
}

Query Deployment details

You can use the workspaceDeployment query to retrieve details about a Deployment in a given Workspace. It requires the following inputs:

Workspace ID: To retrieve this value, use the sysWorkspaces or workspaces query, or run astro workspace list. Alternatively, open a Workspace in the Astro Private Cloud UI and copy the value after /w/ in your Workspace URL, for example, https://app.basedomain/w/<workspace-id>.
Deployment release name: To retrieve this value, run astro deployment list in your Workspace. Alternatively, you can copy the Release name from your Deployment’s Settings tab in the Astro Private Cloud UI. The workspaceDeployment query can return also any of the fields under Type Details, such as:
config
uuid
status
createdAt
updatedAt
roleBindings

For example, you can run the following query to retrieve the Deployment’s:

ID
Health status
Creation time
Update time
Users

query workspaceDeployment {
  workspaceDeployment(
    releaseName: "mathematical-probe-2087"
    workspaceUuid: "ck35y9uf44y8l0a19cmwd1x8x"
  )
  {
    id
    status
    createdAt
    updatedAt
    roleBindings {
      id,
      role,
      user {
        username,
        emails {
          primary
        }
      }
    }
  }
}

Query user details

A common query is users, which lets you retrieve information about multiple users at once. To use this query, you must provide:

At least one of the following userSearch values:
- userId (String): The user’s ID
- userUuid(String): The user’s unique ID
- username (String): The user’s username
- email (String): The user’s email
- fullName (String): The user’s full name
- createdAt(DateTime): When the user was created
- updatedAt(DateTime): When the user was updated

The query returns the requested details for all users who exactly match the values provided for the userSearch. For example, the following query would retrieve the requested values for any user accounts with the email name@mycompany.com:

query User {
  users(user: { email: "name@mycompany.com"} )
  {
    id
    roleBindings {role}
    status
    createdAt
  }
}

Query a Deployment’s effective configuration

The Deployment type exposes the merged deployments object on effectiveConfig (the final value after the Platform through Deployment merge). It also exposes configOverrides for the deployment tier only, when you need the fourth layer in isolation. For example, workspaceDeployment can return the merged result alongside deployment-level overrides:

query {
  workspaceDeployment(
    releaseName: "<release-name>"
    workspaceUuid: "<workspace-id>"
  ) {
    id
    label
    effectiveConfig
    configOverrides {
      config
    }
  }
}

For the full config governance model, see Config governance.

Query teams

Get single team

query {
  team(teamUuid: "<team-uuid>") {
    id
    name
    provider
    description
    createdAt
    updatedAt
    users {
      id
      username
      emails {
        address
      }
    }
    roleBindings {
      role
      workspace {
        id
        label
      }
      deployment {
        id
        label
      }
    }
  }
}

List teams with search

searchPhrase requires a minimum of three characters.

query {
  paginatedTeams(
    take: 20
    pageNumber: 1
    searchPhrase: "engineering"
  ) {
    teams {
      id
      name
      provider
      users {
        id
      }
    }
    count
  }
}

List workspace teams

query {
  workspaceTeams(workspaceUuid: "<workspace-uuid>") {
    id
    name
    roleBindings {
      role
    }
  }
}

List deployment teams

query {
  deploymentTeams(deploymentUuid: "<deployment-uuid>") {
    id
    name
    roleBindings {
      role
    }
  }
}

For the full teams model, roles, and error reference, see team management reference.

Query clusters

List clusters

The paginatedClusters query returns clusters the caller has access to. Pagination uses the take argument, plus either cursor (a cluster UUID) or pageNumber. The response object contains a clusters list and a total count.

query {
  paginatedClusters(
    take: 50
    status: ACTIVE
  ) {
    clusters {
      id
      name
      status
      statusReason
      healthStatus
      k8sVersion
      cloudProvider
      region
      createdAt
      updatedAt
    }
    count
  }
}

Get a single cluster

query {
  cluster(id: "<cluster-id>") {
    id
    name
    status
    statusReason
    healthStatus
    k8sVersion
    cloudProvider
    region
    dpChartVersion
    commanderVersion
    config
    configOverride
  }
}

The healthStatus field returns a JSON object containing the full health payload the APC API received from the deployment orchestrator, not a single string. The statusReason field is also a JSON object.

Filter by cloud provider and region

query {
  paginatedClusters(
    status: INACTIVE
    cloudProvider: "aws"
    region: "us-east-1"
    take: 25
  ) {
    clusters {
      id
      name
      statusReason
    }
    count
  }
}

Other supported filter arguments include searchPhrase, k8sVersion, id, sortBy, and sortDirection. For status values and troubleshooting, see Manage cluster status.

Force a cluster metadata reconciliation

Use the reconcileClusterMetadataJob query to make the APC API refetch metadata from the deployment orchestrator immediately, instead of waiting for the next CronJob run. The query accepts a list of cluster UUIDs; if you pass null or omit the argument, the APC API reconciles every cluster the caller is authorized to update.

query {
  reconcileClusterMetadataJob(
    clusterIds: ["<cluster-id-1>", "<cluster-id-2>"]
  ) {
    successfulClusterIds
    failedClusterIds
    skippedClusterIds
  }
}

A cluster appears in skippedClusterIds when it lacks a data plane URL or when the caller isn’t authorized to reconcile it. See Manage cluster status for when to use this query.

Clean up Airflow metadata

The following examples show different queries you can use depending on your needs. For the full parameter reference, see Clean up and delete task metadata.

Clean up Deployments per Workspace

query cleanupAirflowDb(
  $olderThan: Int!
  $dryRun: Boolean!
  $outputPath: String!
  $dropArchives: Boolean!
  $provider: String!
  $bucketName: String!
  $providerEnvSecretName: String!
  $deploymentIds: [Id]
  $workspaceId: Uuid
  $tables: String!
  $connectionId: String
) {
  cleanupAirflowDb(
    olderThan: $olderThan
    dryRun: $dryRun
    outputPath: $outputPath
    dropArchives: $dropArchives
    provider: $provider
    bucketName: $bucketName
    providerEnvSecretName: $providerEnvSecretName
    workspaceId: $workspaceId
    tables: $tables
    connectionId: $connectionId
  )
}

Query variables to clean up all Deployments older than 1 day within a Workspace that uses GCP as a cloud provider:

{
	"olderThan": 1,
	"dryRun": true,
	"outputPath": "",
	"dropArchives": true,
	"provider":  "gcp",
	"bucketName" : "",
	"connectionId":  "",
	"tables": "callback_request,celery_taskmeta,celery_tasksetmeta,dag,dag_run,dataset_event,import_error,job,log,session,sla_miss,task_fail,task_instance,task_reschedule,trigger,xcom",
	"providerEnvSecretName": "GCP_PASS",
	"workspaceId": "cma40n66l000008l89nye86o1"
}

Clean up specific Deployments

Query variables to clean up specific Deployments older than 1 day within a Workspace:

{
	"olderThan": 1,
	"dryRun": true,
	"outputPath": "",
	"dropArchives": true,
	"provider":  "gcp",
	"bucketName" : "",
	"connectionId":  "",
	"tables": "callback_request,celery_taskmeta,celery_tasksetmeta,dag,dag_run,dataset_event,import_error,job,log,session,sla_miss,task_fail,task_instance,task_reschedule,trigger,xcom",
	"providerEnvSecretName": "GCP_PASS",
	"deploymentIds": ["cma42zc67000108l89eb37iy5","cma42zjdp000208l8g16ygm6m"],
	"workspaceId": "cma42z570000008l8f6rpc72f"
}

Clean up using an Airflow connection ID

Requires configuring an Airflow Connection ID, connectionId, from the Airflow UI or CLI.

Query variables to clean up Deployments and export the cleanup logs to the storage provider configured in an Airflow Connection:

{
	"olderThan": 1,
	"dryRun": true,
	"outputPath": "",
	"dropArchives": true,
	"provider":  "gcp",
	"bucketName" : "",
	"connectionId":  "<airflow_connection_id>",
	"tables": "callback_request,celery_taskmeta,celery_tasksetmeta,dag,dag_run,dataset_event,import_error,job,log,session,sla_miss,task_fail,task_instance,task_reschedule,trigger,xcom",
	"deploymentIds": ["cm6q3jpn61741517mhonzgcgz7","cm6q3jpn61741517mhonzgcgz7"],
	"workspaceId": "cm5nj9wly007617iox80beute"
}

Configure custom Pod resources

If you don’t configure a default Pod CPU or memory resource amount, or want to override one, make a query that sets resourceSpec:

query cleanupAirflowDb(
    $olderThan: Int!
    $dryRun: Boolean!
    $outputPath: String!
    $dropArchives: Boolean!
    $provider: String!
    $bucketName: String!
    $providerEnvSecretName: String!
    $tables: String!
    $resourceSpec: JSON
  ) {
    cleanupAirflowDb(
      olderThan: $olderThan
      dryRun: $dryRun
      outputPath: $outputPath
      dropArchives: $dropArchives
      provider: $provider
      bucketName: $bucketName
      providerEnvSecretName: $providerEnvSecretName
      tables: $tables
      resourceSpec: $resourceSpec
    )
  }

Query variables that configure resource requests and limits for the cleanup run:

{
  "resourceSpec": {
    "requests": {
      "cpu": "100m",
      "memory": "5000Mi"
    },
  "limits": {
      "cpu": "100m",
      "memory": "5000Mi"
    }
  },
  "olderThan": 1,
  "dryRun": false,
  "outputPath": "/abc",
  "dropArchives": false,
  "provider": "aws",
  "bucketName": "test",
  "providerEnvSecretName": "test-secret",
  "tables": "dag"
}

For the full parameter reference, see Clean up and delete task metadata.

Trigger task usage data cleanup

Use the cleanupTaskUsageDataJob query to manually trigger a purge of task usage metrics and audit logs:

query {
  cleanupTaskUsageDataJob(olderThan: 90)
}

Minimum retention is 90 days and can’t be reduced.

For the full cleanup job reference, see Configure cleanup jobs.

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

Example APC API queries

Find the ID of a workspace you belong to

Find the ID of all workspaces

Query Deployment details

Query user details

Query a Deployment’s effective configuration

Query teams

Get single team

List teams with search

List workspace teams

List deployment teams

Query clusters

List clusters

Get a single cluster

Filter by cloud provider and region

Force a cluster metadata reconciliation

Clean up Airflow metadata

Clean up Deployments per Workspace

Clean up specific Deployments

Clean up using an Airflow connection ID

Configure custom Pod resources

Trigger task usage data cleanup

​Find the ID of a workspace you belong to

​Find the ID of all workspaces

​Query Deployment details

​Query user details

​Query a Deployment’s effective configuration

​Query teams

​Get single team

​List teams with search

​List workspace teams

​List deployment teams

​Query clusters

​List clusters

​Get a single cluster

​Filter by cloud provider and region

​Force a cluster metadata reconciliation

​Clean up Airflow metadata

​Clean up Deployments per Workspace

​Clean up specific Deployments

​Clean up using an Airflow connection ID

​Configure custom Pod resources

​Trigger task usage data cleanup

Find the ID of a workspace you belong to

Find the ID of all workspaces

Query Deployment details

Query user details

Query a Deployment’s effective configuration

Query teams

Get single team

List teams with search

List workspace teams

List deployment teams

Query clusters

List clusters

Get a single cluster

Filter by cloud provider and region

Force a cluster metadata reconciliation

Clean up Airflow metadata

Clean up Deployments per Workspace

Clean up specific Deployments

Clean up using an Airflow connection ID

Configure custom Pod resources

Trigger task usage data cleanup