# Query your fleet and inspect impact

Use connected Kubernetes edges as a searchable inventory.

Source: https://faros.sh/docs/use/kuery/quickstart/


## Prerequisites

Enable **Edges** and **Kuery** in the same workspace, with a connected Kubernetes edge. The provider must have its required edge access. Allow time for synchronization before expecting query results.

1. Open Kuery in the selected workspace.
2. Inspect fleet inventory and select an edge, resource kind, or namespace.
3. Open a resource’s impact view to inspect its declared relationships.
4. Compare an expected object against the live edge when freshness matters.

For API clients, the query endpoint accepts a structured query rather than free-form SQL. A Deployment inventory query is:

```json
{
  "filter": {"objects": [{"groupKind": {"kind": "Deployment"}}]},
  "objects": {"cluster": true}
}
```

## Submit the query from a terminal

Save the JSON above as `query.json`. Use a valid human-session bearer token and the organization/workspace UUIDs for the intended Faros workspace. These are UUIDs, not display names; obtain them from your console context or administrator. `curl` does not inherit the workspace selected by `kubectl faros use`.

Set `FAROS_HUB_URL`, `FAROS_ORG_UUID`, and `FAROS_WORKSPACE_UUID` to those values. Supply `FAROS_TOKEN` securely in your local environment; do not paste the token into shell history or shared output.

```bash
curl --fail-with-body --silent --show-error \
  "${FAROS_HUB_URL}/services/providers/kuery/api/query" \
  -H "Authorization: Bearer ${FAROS_TOKEN}" \
  -H "X-Faros-Org: ${FAROS_ORG_UUID}" \
  -H "X-Faros-Workspace: ${FAROS_WORKSPACE_UUID}" \
  -H "Content-Type: application/json" \
  --data-binary @query.json
```

The response is a query result with `objects`; an empty collection may indicate filtering or synchronization state. A 401/403 is an authentication or workspace-access problem, not an empty fleet. Do not supply `X-Faros-Tenant`: the hub establishes the provider's tenant scope. Do not assume a service-account token has the same provider-proxy support as a human session.

Delete the test query file when no longer needed and unset `FAROS_TOKEN` after use. Queries do not deploy or change fleet workloads.

## Interpret results carefully

An empty result may mean the cluster has not synchronized, the kind is excluded by the sync whitelist, or the filter does not match. A dependency graph describes observed relationships; it does not prove that deleting or changing a resource is safe.

Queries do not create workloads, so no workload cleanup is needed for this guide. Next: [query reference and freshness](https://faros.sh/docs/reference/providers/kuery/).

## Troubleshooting

### Check workspace and access

Confirm the selected organization/workspace and that the provider is enabled there. Try a read-only operation using the same identity as the failing action. A successful administrator action does not prove another identity has access.

### Diagnose the provider

Check edge connectivity, synchronization status, sync whitelist, filters, and workspace. The query store can lag the source cluster. Compare a known object to the live edge before interpreting an empty result as absence.

### Collect useful evidence

Record the resource name, failing step, time, status conditions, and request/run ID where available. Share these with your operator, excluding bearer tokens, credentials, and private application data.

If the provider itself is unavailable, use [Kuery self-hosting](https://faros.sh/docs/self-hosting/providers/kuery/) for operator checks. Once resolved, repeat the verification step in the [quickstart](https://faros.sh/docs/use/kuery/quickstart/).