Management APIs / Projects

List project instances

GEThttps://api.spice.ai/v1/projects/{projectId}/instances

Lists the runtime instances of a deployed project, newest first. A managed or BYOC project lists its Spicepod instances. A standalone project lists its Cloud Connect runtime. Read the logs of an instance with GET /v1/projects/{projectId}/instances/{instanceName}/logs.

Authorizations

  • AuthorizationstringRequired

    Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

  • projectIdintegerRequired

    The ID of the project

Header parameters

  • X-Org-Namestring

    The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but GET /v1/orgs (400 org_assertion_required otherwise).

    • Pattern: ^[A-Za-z0-9._-]{1,255}$

Responses

200The project's instancesapplication/json

  • instancesarray of objectRequired

    3 properties

    • namestringRequired

      The instance name: a Spicepod instance (pod) name, or a Cloud Connect runtime id. Pass it as instanceName to read its logs.

    • statusstringRequired

      A Spicepod instance is deploying, loading, ready, unhealthy, terminating, failed, or failed_to_start. A Cloud Connect runtime is online or offline.

      • Allowed values: deploying, loading, ready, unhealthy, terminating, failed, failed_to_start, online, offline

    • started_atstring (date-time) | nullRequired

      When the Spicepod instance started, or when the Cloud Connect runtime enrolled.

400Invalid project ID

401Unauthorized

403Insufficient scope

404Project not found

409Conflictapplication/json

The project has no running instances. code is project_not_deployed when a managed or BYOC project was never deployed, or project_paused when the project is paused.

  • errorstringRequired

  • codestringRequired

    • Allowed values: project_not_deployed, project_paused

422The project is not fully configured

500Internal server error

503The project runtime did not answer

curl "https://api.spice.ai/v1/projects/<projectId>/instances" \
  -H "Authorization: Bearer <token>"
{
  "instances": [
    {
      "name": "string",
      "status": "deploying",
      "started_at": "2026-01-01T00:00:00Z"
    }
  ]
}

application/json

GEThttps://api.spice.ai/v1/orgs/{orgId}/projects/{projectId}/instances

The org is orgId in the path. Lists the runtime instances of a deployed project, newest first. A managed or BYOC project lists its Spicepod instances. A standalone project lists its Cloud Connect runtime. Read the logs of an instance with GET /v1/projects/{projectId}/instances/{instanceName}/logs.

Authorizations

  • AuthorizationstringRequired

    Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

  • orgIdintegerRequired

    The org id from GET /v1/orgs

    • Minimum: 1

  • projectIdintegerRequired

    The ID of the project

Header parameters

  • X-Org-Namestring

    When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400).

    • Pattern: ^[A-Za-z0-9._-]{1,255}$

Responses

200The project's instancesapplication/json

  • instancesarray of objectRequired

    3 properties

    • namestringRequired

      The instance name: a Spicepod instance (pod) name, or a Cloud Connect runtime id. Pass it as instanceName to read its logs.

    • statusstringRequired

      A Spicepod instance is deploying, loading, ready, unhealthy, terminating, failed, or failed_to_start. A Cloud Connect runtime is online or offline.

      • Allowed values: deploying, loading, ready, unhealthy, terminating, failed, failed_to_start, online, offline

    • started_atstring (date-time) | nullRequired

      When the Spicepod instance started, or when the Cloud Connect runtime enrolled.

400Bad Request

Invalid project ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).

401Unauthorized

403Forbidden

Insufficient scope. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).

404Project not found

409Conflictapplication/json

The project has no running instances. code is project_not_deployed when a managed or BYOC project was never deployed, or project_paused when the project is paused.

  • errorstringRequired

  • codestringRequired

    • Allowed values: project_not_deployed, project_paused

422The project is not fully configured

500Internal server error

503The project runtime did not answer

curl "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/instances" \
  -H "Authorization: Bearer <token>"
{
  "instances": [
    {
      "name": "string",
      "status": "deploying",
      "started_at": "2026-01-01T00:00:00Z"
    }
  ]
}

application/json

GEThttps://api.spice.ai/v1/apps/{appId}/instancesDeprecated

Legacy alias of /v1/projects/{projectId}/instances — projects were previously called apps. Lists the runtime instances of a deployed project, newest first. A managed or BYOC project lists its Spicepod instances. A standalone project lists its Cloud Connect runtime. Read the logs of an instance with GET /v1/projects/{projectId}/instances/{instanceName}/logs.

Authorizations

  • AuthorizationstringRequired

    Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

  • appIdintegerRequired

    The ID of the project

Header parameters

  • X-Org-Namestring

    The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but GET /v1/orgs (400 org_assertion_required otherwise).

    • Pattern: ^[A-Za-z0-9._-]{1,255}$

Responses

200The project's instancesapplication/json

  • instancesarray of objectRequired

    3 properties

    • namestringRequired

      The instance name: a Spicepod instance (pod) name, or a Cloud Connect runtime id. Pass it as instanceName to read its logs.

    • statusstringRequired

      A Spicepod instance is deploying, loading, ready, unhealthy, terminating, failed, or failed_to_start. A Cloud Connect runtime is online or offline.

      • Allowed values: deploying, loading, ready, unhealthy, terminating, failed, failed_to_start, online, offline

    • started_atstring (date-time) | nullRequired

      When the Spicepod instance started, or when the Cloud Connect runtime enrolled.

400Invalid project ID

401Unauthorized

403Insufficient scope

404Project not found

409Conflictapplication/json

The project has no running instances. code is project_not_deployed when a managed or BYOC project was never deployed, or project_paused when the project is paused.

  • errorstringRequired

  • codestringRequired

    • Allowed values: project_not_deployed, project_paused

422The project is not fully configured

500Internal server error

503The project runtime did not answer

OpenAPIapi.spice.ai/openapi.json

curl "https://api.spice.ai/v1/apps/<appId>/instances" \
  -H "Authorization: Bearer <token>"
{
  "instances": [
    {
      "name": "string",
      "status": "deploying",
      "started_at": "2026-01-01T00:00:00Z"
    }
  ]
}

application/json