Call the Public API with npx nx-cloud api from your workspace, in a terminal or a script. It authenticates with your login from npx nx login, or with a CI access token.
To send requests without the Nx Cloud CLI, use one of these credentials:
- A CI access token, sent as a bearer token.
- A personal access token (PAT) and Nx Cloud Id, sent together in two headers.
The Nx Cloud Id alone does not authenticate a Public API request. Service-account credentials for the Prometheus metrics API do not authenticate Public API requests.
Use nx-cloud api
Section titled “Use nx-cloud api”npx nx-cloud api cipesThe command sends the login stored on your machine, with the nxCloudId from your nx.json, and refreshes an OAuth login when it expires. If you aren't logged in, run npx nx login and approve the code in your browser.
In CI, set NX_CLOUD_ACCESS_TOKEN to a CI access token. Whenever that variable is set, the command sends it instead of your login.
Run npx nx-cloud api --help for paths, filters, and pagination.
Rate limits
Section titled “Rate limits”The organization must be enabled, and your credential must have access to the workspace.
All workspaces and access tokens in an organization share one request quota, and the organization's plan sets its default:
| Plan | Requests per minute |
|---|---|
| Free, Legacy | 30 |
| Team, Pro, OSS | 60 |
| Enterprise | 2,500 |
A request over the quota returns 429 with the error code rate_limit_exceeded. Wait the number of seconds in the Retry-After header before you retry.
Choose your API host
Section titled “Choose your API host”Use the host that serves your workspace:
https://cloud.nx.appfor the US region.https://eu.nx.appfor the EU region.- Your deployment URL for a single-tenant installation.
The examples below require curl and jq. They discover the CI pipeline execution (CIPE) collection path from your deployment, so they do not assume an API version.
export NX_CLOUD_HOST="https://cloud.nx.app"
curl --fail --silent --show-error \ "$NX_CLOUD_HOST/nx-cloud/data/openapi.json" \ --output openapi.json
CIPES_PATH=$(jq -r '.paths | keys[] | select(endswith("/cipes"))' openapi.json)Use a CI access token
Section titled “Use a CI access token”Create a CI access token in your Nx Cloud workspace settings, under Access Control. See CI access tokens for token management.
Store the token in your secret manager. Provide it to your shell or CI environment as NX_CLOUD_ACCESS_TOKEN.
Send the token in the Authorization header:
curl --fail-with-body --silent --show-error --get \ "$NX_CLOUD_HOST$CIPES_PATH" \ --header "Authorization: Bearer $NX_CLOUD_ACCESS_TOKEN" \ --data-urlencode "limit=10"The token identifies its workspace. This option does not require an Nx-Cloud-Id header.
Use a personal access token and Nx Cloud Id
Section titled “Use a personal access token and Nx Cloud Id”Use a PAT for a script that acts as you and can't run the Nx Cloud CLI. Create one in Nx Cloud under Personal settings > Access tokens.
Store the PAT in your secret manager. Provide it to your script as NX_CLOUD_PERSONAL_ACCESS_TOKEN.
Find the Nx Cloud Id in the nxCloudId property of your workspace's nx.json, or in the workspace's General settings. Set NX_CLOUD_WORKSPACE_ID to that value:
export NX_CLOUD_WORKSPACE_ID="<nx-cloud-id>"Send both headers in the same request:
curl --fail-with-body --silent --show-error --get \ "$NX_CLOUD_HOST$CIPES_PATH" \ --header "Nx-Cloud-Personal-Access-Token: $NX_CLOUD_PERSONAL_ACCESS_TOKEN" \ --header "Nx-Cloud-Id: $NX_CLOUD_WORKSPACE_ID" \ --data-urlencode "limit=10"The PAT and Nx Cloud Id are required together. Use these two headers instead of the CI bearer header.
Keep credentials secure
Section titled “Keep credentials secure”Do not commit tokens to your repository or include them in logs, prompts, or reports. Send credentials only to your Nx Cloud API host. Do not forward them to signed asset-download URLs.
If a request returns 401, check the token and its header. For PAT authentication, check that both the PAT and Nx Cloud Id headers are present.
See Query the Nx Cloud Public API for filters, pagination, and asset downloads. Use the API reference to look up endpoints, response schemas, and errors.