Skip to content
ClawHosters ClawHosters
Login Get Started
Subs -25% LAUNCH-SUB
Claws -25% LAUNCH-CLAWS

API: List Instances

3 min read API Last updated February 10, 2026

Endpoint

text 
GET /api/v1/instances

Returns all instances belonging to the authenticated customer.

Authentication

Include your API key in the Authorization header:

text 
Authorization: Bearer oc_live_your_api_key_here

See API Overview for details on obtaining and managing API keys.

Request

No request body or query parameters are required. The endpoint returns all instances for the authenticated customer.

Example:

bash 
curl -X GET https://clawhosters.com/api/v1/instances \
  -H "Authorization: Bearer oc_live_your_api_key_here" \
  -H "Content-Type: application/json"

Response

Success (200 OK)

The response contains a data array with one object per instance.

json 
{
  "data": [
    {
      "id": 1,
      "name": "my-ai-bot",
      "status": "running",
      "tier": "balanced",
      "billing_mode": "daily",
      "ip_address": "2a01:4f9:0:0::abcd:1234",
      "health_status": "healthy",
      "created_at": "2026-02-05T12:34:56Z",
      "provisioned_at": "2026-02-05T12:40:22Z"
    },
    {
      "id": 2,
      "name": "experimental-setup",
      "status": "pending_configuration",
      "tier": "budget",
      "billing_mode": "monthly",
      "ip_address": "2a01:4f9:0:0::abcd:5678",
      "health_status": "unknown",
      "created_at": "2026-02-08T08:15:10Z",
      "provisioned_at": null
    }
  ]
}

If you have no instances, the data array is empty:

json 
{
  "data": []
}

Response Fields

Field Type Description
id integer Unique instance identifier
name string Instance name set during creation
status string Current instance status (see below)
tier string Instance tier: budget, balanced, or pro
billing_mode string daily (Claws) or monthly (Stripe subscription)
ip_address string IPv6 address of the VPS. Null if not yet provisioned
health_status string healthy, unhealthy, or unknown
created_at string ISO 8601 timestamp of when the instance was created
provisioned_at string or null ISO 8601 timestamp of when the instance became running. Null if not yet provisioned

Instance Statuses

Status Description
provisioning VPS is being created on Hetzner Cloud
deploying Application is being deployed to the VPS
deploy_failed Deployment failed after retry attempts
pending_configuration Instance is running but awaiting LLM configuration
running Instance is operational and healthy
stopped Instance is powered off
paused Instance was paused (insufficient Claws balance or manual pause). Data is preserved in a snapshot
error Instance is in an error state
deleting Instance deletion is in progress

Error Responses

Unauthorized (401)

Returned when the API key is missing, invalid, or revoked.

json 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Rate Limit Exceeded (429)

Returned when you exceed 100 requests per minute.

json 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 42 seconds."
  }
}

Check the X-RateLimit-Remaining and X-RateLimit-Reset response headers to manage your request rate.

Rate Limiting

Header Description
X-RateLimit-Limit Maximum requests per minute (100)
X-RateLimit-Remaining Requests remaining in the current window
X-RateLimit-Reset Unix timestamp when the window resets

Notes

  • The endpoint returns all instances for the authenticated customer. Deleted instances are excluded.
  • Timestamps are in UTC and formatted as ISO 8601 strings.
  • The ip_address field may be null for instances that are still being provisioned or that have been paused (their VPS is snapshotted and the server deleted).
  • The health_status reflects the most recent health check. It may show unknown for instances that are not yet running.
  • API Overview — Authentication, rate limits, and response format

Related Documentation

API: Get Instance Details

Endpoint text Copy GET /api/v1/instances/:id Returns detailed inf...

API Overview

Introduction The ClawHosters API lets you manage your instances, check billing, and control add-...

API: Instance Actions (Start/Stop/Restart)

Overview Control your instance's power state using these endpoints. Each action changes the inst...