APC API

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.

1query {
2  workspaces(label:"example-workspace") {
3    id,
4    label
5  }
6}

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.

1query {
2  sysWorkspaces {
3    id,
4    label
5  }
6}

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
1query workspaceDeployment {
2  workspaceDeployment(
3    releaseName: "mathematical-probe-2087"
4    workspaceUuid: "ck35y9uf44y8l0a19cmwd1x8x"
5  )
6  {
7    id
8    status
9    createdAt
10    updatedAt
11    roleBindings {
12      id,
13      role,
14      user {
15        username,
16        emails {
17          primary
18        }
19      }
20    }
21  }
22}

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:

1query User {
2  users(user: { email: "name@mycompany.com"} )
3  {
4    id
5    roleBindings {role}
6    status
7    createdAt
8  }
9}

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:

1query {
2  workspaceDeployment(
3    releaseName: "<release-name>"
4    workspaceUuid: "<workspace-id>"
5  ) {
6    id
7    label
8    effectiveConfig
9    configOverrides {
10      config
11    }
12  }
13}

For the full config governance model, see Config governance.

Query teams

Get single team

1query {
2  team(teamUuid: "<team-uuid>") {
3    id
4    name
5    provider
6    description
7    createdAt
8    updatedAt
9    users {
10      id
11      username
12      emails {
13        address
14      }
15    }
16    roleBindings {
17      role
18      workspace {
19        id
20        label
21      }
22      deployment {
23        id
24        label
25      }
26    }
27  }
28}

searchPhrase requires a minimum of three characters.

1query {
2  paginatedTeams(
3    take: 20
4    pageNumber: 1
5    searchPhrase: "engineering"
6  ) {
7    teams {
8      id
9      name
10      provider
11      users {
12        id
13      }
14    }
15    count
16  }
17}

List workspace teams

1query {
2  workspaceTeams(workspaceUuid: "<workspace-uuid>") {
3    id
4    name
5    roleBindings {
6      role
7    }
8  }
9}

List deployment teams

1query {
2  deploymentTeams(deploymentUuid: "<deployment-uuid>") {
3    id
4    name
5    roleBindings {
6      role
7    }
8  }
9}

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.

1query {
2  paginatedClusters(
3    take: 50
4    status: ACTIVE
5  ) {
6    clusters {
7      id
8      name
9      status
10      statusReason
11      healthStatus
12      k8sVersion
13      cloudProvider
14      region
15      createdAt
16      updatedAt
17    }
18    count
19  }
20}

Get a single cluster

1query {
2  cluster(id: "<cluster-id>") {
3    id
4    name
5    status
6    statusReason
7    healthStatus
8    k8sVersion
9    cloudProvider
10    region
11    dpChartVersion
12    commanderVersion
13    config
14    configOverride
15  }
16}

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

1query {
2  paginatedClusters(
3    status: INACTIVE
4    cloudProvider: "aws"
5    region: "us-east-1"
6    take: 25
7  ) {
8    clusters {
9      id
10      name
11      statusReason
12    }
13    count
14  }
15}

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.

1query {
2  reconcileClusterMetadataJob(
3    clusterIds: ["<cluster-id-1>", "<cluster-id-2>"]
4  ) {
5    successfulClusterIds
6    failedClusterIds
7    skippedClusterIds
8  }
9}

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

1query cleanupAirflowDb(
2  $olderThan: Int!
3  $dryRun: Boolean!
4  $outputPath: String!
5  $dropArchives: Boolean!
6  $provider: String!
7  $bucketName: String!
8  $providerEnvSecretName: String!
9  $deploymentIds: [Id]
10  $workspaceId: Uuid
11  $tables: String!
12  $connectionId: String
13) {
14  cleanupAirflowDb(
15    olderThan: $olderThan
16    dryRun: $dryRun
17    outputPath: $outputPath
18    dropArchives: $dropArchives
19    provider: $provider
20    bucketName: $bucketName
21    providerEnvSecretName: $providerEnvSecretName
22    workspaceId: $workspaceId
23    tables: $tables
24    connectionId: $connectionId
25  )
26}

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

1{
2	"olderThan": 1,
3	"dryRun": true,
4	"outputPath": "",
5	"dropArchives": true,
6	"provider":  "gcp",
7	"bucketName" : "",
8	"connectionId":  "",
9	"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",
10	"providerEnvSecretName": "GCP_PASS",
11	"workspaceId": "cma40n66l000008l89nye86o1"
12}

Clean up specific Deployments

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

1{
2	"olderThan": 1,
3	"dryRun": true,
4	"outputPath": "",
5	"dropArchives": true,
6	"provider":  "gcp",
7	"bucketName" : "",
8	"connectionId":  "",
9	"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",
10	"providerEnvSecretName": "GCP_PASS",
11	"deploymentIds": ["cma42zc67000108l89eb37iy5","cma42zjdp000208l8g16ygm6m"],
12	"workspaceId": "cma42z570000008l8f6rpc72f"
13}

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:

1{
2	"olderThan": 1,
3	"dryRun": true,
4	"outputPath": "",
5	"dropArchives": true,
6	"provider":  "gcp",
7	"bucketName" : "",
8	"connectionId":  "<airflow_connection_id>",
9	"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",
10	"deploymentIds": ["cm6q3jpn61741517mhonzgcgz7","cm6q3jpn61741517mhonzgcgz7"],
11	"workspaceId": "cm5nj9wly007617iox80beute"
12}

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:

1query cleanupAirflowDb(
2    $olderThan: Int!
3    $dryRun: Boolean!
4    $outputPath: String!
5    $dropArchives: Boolean!
6    $provider: String!
7    $bucketName: String!
8    $providerEnvSecretName: String!
9    $tables: String!
10    $resourceSpec: JSON
11  ) {
12    cleanupAirflowDb(
13      olderThan: $olderThan
14      dryRun: $dryRun
15      outputPath: $outputPath
16      dropArchives: $dropArchives
17      provider: $provider
18      bucketName: $bucketName
19      providerEnvSecretName: $providerEnvSecretName
20      tables: $tables
21      resourceSpec: $resourceSpec
22    )
23  }

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

1{
2  "resourceSpec": {
3    "requests": {
4      "cpu": "100m",
5      "memory": "5000Mi"
6    },
7  "limits": {
8      "cpu": "100m",
9      "memory": "5000Mi"
10    }
11  },
12  "olderThan": 1,
13  "dryRun": false,
14  "outputPath": "/abc",
15  "dropArchives": false,
16  "provider": "aws",
17  "bucketName": "test",
18  "providerEnvSecretName": "test-secret",
19  "tables": "dag"
20}

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:

1query {
2  cleanupTaskUsageDataJob(olderThan: 90)
3}

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

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