API: Get Instance Details

Endpoint

GET /api/v1/instances/:id

Returns detailed information about a single instance, including action availability and configuration status.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer oc_live_your_api_key_here

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

Request

Replace :id with the numeric instance ID.

Example:

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

Response

Success (200 OK)

{
  "data": {
    "id": 42,
    "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",
    "can_start": false,
    "can_stop": true,
    "can_restart": true,
    "subdomain_url": "my-ai-bot.clawhosters.com",
    "daily_claw_cost": 225,
    "llm_configured": true,
    "telegram_configured": true
  }
}

Response Fields

The detail response includes all fields from List Instances, plus additional fields:

Action Availability

The can_start, can_stop, and can_restart fields tell you which power actions are available for the instance in its current state. Check these before calling the corresponding action endpoints.

Error Responses

Not Found (404)

Returned when the instance ID does not exist or belongs to a different customer.

{
  "error": {
    "code": "not_found",
    "message": "Instance not found"
  }
}

Unauthorized (401)

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

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

Rate Limit Exceeded (429)

Returned when you exceed 100 requests per minute.

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

Rate Limiting

Notes

• You can only view instances that belong to your account. Attempting to access another customer's instance returns a 404.
• The daily_claw_cost reflects the tier's base cost. Add-on costs are tracked separately.
• The subdomain_url is assigned during provisioning and remains the same even if the instance is stopped and restarted.
• The llm_configured and telegram_configured flags help you determine whether the instance is ready to handle messages.

Related Docs

• API Overview — Authentication, rate limits, and response format
• List Instances — List all your instances
• Instance Actions — Start, stop, and restart instances
• Delete Instance — Permanently remove an instance