> ## Documentation Index > Fetch the complete documentation index at: https://docs.hivenet.com/llms.txt > Use this file to discover all available pages before exploring further. # List your instances > Returns a cursor-paginated list of your instances, newest first. Only instances belonging to your account are returned. There is no way to widen the result set to another account or organisation. ## OpenAPI ````yaml /public-v1.yaml get /instances openapi: 3.0.3 info: title: Hive Compute Public API description: | The Hive Compute public API lets you manage compute instances and SSH keys programmatically, and browse the hardware presets and regions available to you. **Base URL:** `https://api.hivenet.com/v1` ## Authentication Every endpoint requires an API key, sent as a Bearer token: ``` Authorization: Bearer ``` API keys are issued manually at this release. Email [support@hivenet.com](mailto:support@hivenet.com) to request one. There is no self-service endpoint or console page for creating, listing or rotating keys yet; both will arrive in a later release. Treat the key as a password. It carries the full permissions of your account, does not expire on its own, and can only be replaced by contacting support. ## Scope Requests are scoped to the account the key belongs to. You can only see and act on your own instances and SSH keys. Regions and presets are the shared public catalogue and look the same to everyone. ## Errors Every error shares one envelope: ```json { "error": { "code": "NOT_FOUND", "message": "Instance 7f3c... not found", "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ``` Quote `request_id` when contacting support: it identifies the exact request in our logs. ## Rate limiting Requests are rate limited per key. Exceeding the limit returns `429` with a `Retry-After` header giving the number of seconds to wait. Treat the limit as subject to change and back off on `429` rather than pacing to a fixed number. ## Pagination List endpoints are cursor-paginated and return the same envelope: ```json { "data": [], "pagination": { "next": "opaque-cursor", "size": 50 } } ``` Pass `pagination.next` back as the `cursor` query parameter to fetch the following page. When it is `null` you have reached the last page. Cursors are opaque; do not construct or parse them. version: 1.0.0 contact: name: Hive Compute Support email: support@hivenet.com url: https://hivenet.com servers: - url: https://api.hivenet.com/v1 description: Production security: - bearerAuth: [] tags: - name: Instances description: > Compute instances are the core resource of the platform. Each instance runs a GPU-backed workload on a hardware preset in a region, and moves through this lifecycle: `CREATED → DEPLOYED → STARTING → RUNNING → STOPPING → STOPPED → TERMINATING → TERMINATED` A stopped instance can be started again and keeps its storage. A terminated instance is gone permanently and cannot be recovered. - name: SSH keys description: | Public keys used to reach your instances over SSH. A key you register is owned by your account and is not visible to anyone else. - name: Catalogue description: | The regions and hardware presets available to launch instances on. This is shared public reference data, identical for every caller. paths: /instances: get: tags: - Instances summary: List your instances description: | Returns a cursor-paginated list of your instances, newest first. Only instances belonging to your account are returned. There is no way to widen the result set to another account or organisation. operationId: listInstances parameters: - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/Size' - name: status in: query description: Return only instances in this state. schema: type: string enum: - running - stopped - terminated - errored - name: region in: query description: Return only instances in this region, e.g. `eu-west`. schema: type: string - name: gpu_type in: query description: Return only instances on this GPU model, e.g. `RTX 4090`. schema: type: string - name: date_range_begin in: query description: Return only instances created at or after this ISO 8601 timestamp. schema: type: string format: date-time - name: date_range_end in: query description: Return only instances created at or before this ISO 8601 timestamp. schema: type: string format: date-time - name: free_text_search in: query description: Match against instance name, region and GPU type. schema: type: string maxLength: 255 - name: sort_field in: query description: Field to order by. Defaults to creation time, newest first. schema: type: string enum: - NAME - GPU_TYPE - SIZE - REGION - HOURLY_RATE - CURRENT_COST - STATUS - name: sort_direction in: query description: Order direction. Defaults to `DESC`. schema: type: string enum: - ASC - DESC responses: '200': description: A page of instances. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Instance' pagination: $ref: '#/components/schemas/Pagination' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: Cursor: name: cursor in: query required: false description: | Opaque cursor from a previous response's `pagination.next`. Omit to start at the first page. schema: type: string Size: name: size in: query required: false description: Number of items per page. schema: type: integer minimum: 1 maximum: 200 default: 50 schemas: Instance: type: object properties: instance_id: type: string format: uuid description: Unique identifier. name: type: string description: Display name. example: training-run-4 status: type: string enum: - CREATED - DEPLOYED - STARTING - RUNNING - ERRORED - TERMINATING - TERMINATED - STOPPING - STOPPED description: Current lifecycle state. region: type: string description: Region the instance runs in. example: eu-west gpu_type: type: string description: GPU model. example: RTX 4090 size: type: string description: SKU name of the preset the instance runs on. example: 8x-RTX-4090 cpu_count: type: integer description: Virtual CPUs allocated. resources: type: string description: Human-readable summary of the allocated hardware. bandwidth: type: number description: Allocated bandwidth, in Mbps. storage_used_gb: type: number description: Storage currently in use, in GB. hourly_rate: type: number description: Price charged per hour while running, in credits. current_cost: type: number description: Cost accrued during the current run, in credits. total_cost_incurred: type: number description: Total cost over the instance's whole life, in credits. total_runtime_hours: type: number description: Total hours the instance has spent running. ttl_remaining_hours: type: number description: Hours remaining before the instance is stopped automatically. started_at: type: string format: date-time nullable: true description: When the instance last entered `RUNNING`. terminated_at: type: string format: date-time nullable: true description: When the instance was terminated, if it has been. termination_reason: type: string nullable: true description: Why the instance was terminated, if it has been. guest_ready: type: string description: Whether the guest OS has finished booting and is reachable. guest_ready_reason: type: string nullable: true description: Explanation when the guest is not ready. Pagination: type: object description: Cursor pagination metadata. properties: next: type: string nullable: true description: | Cursor for the following page, or `null` on the last page. example: eyJjcmVhdGVkX2F0IjoiMjAyNi0wNy0yOSJ9 size: type: integer description: Page size used for this response. example: 50 Error: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - VALIDATION_ERROR - TOO_MANY_REQUESTS - INTERNAL_ERROR description: Stable, machine-readable error code. message: type: string description: Human-readable explanation. Do not match on this text. request_id: type: string description: Identifies this request in our logs. Quote it to support. responses: ValidationError: description: The request was malformed or a parameter was invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: size must not be greater than 200 request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unauthorized: description: The API key is missing, malformed or not valid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Missing API token request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 RateLimited: description: | Too many requests. Wait the number of seconds given in `Retry-After` before retrying. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: TOO_MANY_REQUESTS message: Too Many Requests request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 InternalError: description: >- Something went wrong on our side. Retry, then contact support with the `request_id`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: Internal server error request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 securitySchemes: bearerAuth: type: http scheme: bearer description: | An API key issued by Hive Compute support. See **Authentication** above for how to request one. ````