> ## 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.

# Example APC API queries

<Note>
  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](/docs/astro-private-cloud/v-2-x/houston-api-develop-test) for more on using the built-in GraphQL explorer.
</Note>

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

<a id="workspaces" />

## 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.

```graphql wrap theme={null}
query {
  workspaces(label:"example-workspace") {
    id,
    label
  }
}
```

<a id="sysWorkspaces" />

### 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.

```graphql wrap theme={null}
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`](#sysWorkspaces) or [`workspaces`](#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

```graphql wrap theme={null}
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`:

```graphql wrap theme={null}
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:

```graphql wrap theme={null}
query {
  workspaceDeployment(
    releaseName: "<release-name>"
    workspaceUuid: "<workspace-id>"
  ) {
    id
    label
    effectiveConfig
    configOverrides {
      config
    }
  }
}
```

For the full config governance model, see [Config governance](/docs/astro-private-cloud/v-2-x/config-governance).

### Query teams

### Get single team

```graphql wrap theme={null}
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

<Note>
  `searchPhrase` requires a minimum of three characters.
</Note>

```graphql wrap theme={null}
query {
  paginatedTeams(
    take: 20
    pageNumber: 1
    searchPhrase: "engineering"
  ) {
    teams {
      id
      name
      provider
      users {
        id
      }
    }
    count
  }
}
```

### List workspace teams

```graphql wrap theme={null}
query {
  workspaceTeams(workspaceUuid: "<workspace-uuid>") {
    id
    name
    roleBindings {
      role
    }
  }
}
```

### List deployment teams

```graphql wrap theme={null}
query {
  deploymentTeams(deploymentUuid: "<deployment-uuid>") {
    id
    name
    roleBindings {
      role
    }
  }
}
```

For the full teams model, roles, and error reference, see [team management reference](/docs/astro-private-cloud/v-2-x/team-management-api).

### 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`.

```graphql wrap theme={null}
query {
  paginatedClusters(
    take: 50
    status: ACTIVE
  ) {
    clusters {
      id
      name
      status
      statusReason
      healthStatus
      k8sVersion
      cloudProvider
      region
      createdAt
      updatedAt
    }
    count
  }
}
```

### Get a single cluster

```graphql wrap theme={null}
query {
  cluster(id: "<cluster-id>") {
    id
    name
    status
    statusReason
    healthStatus
    k8sVersion
    cloudProvider
    region
    dpChartVersion
    commanderVersion
    config
    configOverride
  }
}
```

<Note>
  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.
</Note>

### Filter by cloud provider and region

```graphql wrap theme={null}
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](/docs/astro-private-cloud/v-2-x/cluster-status-management).

<a id="reconcileClusterMetadataJob" />

### 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.

```graphql wrap theme={null}
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](/docs/astro-private-cloud/v-2-x/cluster-status-management) 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](/docs/astro-private-cloud/v-2-x/clean-up-task-metadata#apc-api-parameters).

### Clean up Deployments per Workspace

```graphql wrap theme={null}
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:

```graphql wrap theme={null}
{
	"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:

```graphql wrap theme={null}
{
	"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

<Warning>Requires configuring an Airflow Connection ID, `connectionId`, from the Airflow UI or CLI.</Warning>

Query variables to clean up Deployments and export the cleanup logs to the storage provider configured in an [Airflow Connection](/docs/learn/connections):

```graphql wrap theme={null}
{
	"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`:

```graphql wrap theme={null}
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:

```graphql wrap theme={null}
{
  "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](/docs/astro-private-cloud/v-2-x/clean-up-task-metadata#apc-api-parameters).

### Trigger task usage data cleanup

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

```graphql wrap theme={null}
query {
  cleanupTaskUsageDataJob(olderThan: 90)
}
```

<Note>
  Minimum retention is 90 days and can't be reduced.
</Note>

For the full cleanup job reference, see [Configure cleanup jobs](/docs/astro-private-cloud/v-2-x/cleanup-cronjobs).