List devices

This endpoint requires authentication. Include your API key in the X-API-KEY header with every request.

GET/hoster/v1/devices

Paginated list of the hoster's non-archived devices, newest first, each with its setup stage, who uses it, its marketplace state, its live self-rent and its IP rotation. A device must match every filter given. The proxied tunnel is served per-device by GET /hoster/v1/devices/{id}/self-rent/tunnel.

Query Parameters

Name	Type	Required	Description
page	number	Optional	1-based page number, default 1; a page past the end has no items.(default: `1`)
limit	number	Optional	Page size, 1 to 100; defaults to 20.(default: `20`)
rentalStatus	"sold" \| "self_rented" \| "idle"	Optional	Only devices in this use: self_rented (the hoster holds a live self-rent rental), sold (a marketplace buyer holds it) or idle (neither).
marketplaceStatus	"listed" \| "not_listed"	Optional	Only devices in this marketplace state: listed (its current listing is buyable or bought) or not_listed.
setupStatus	"awaiting_device_details" \| "awaiting_agent" \| "active" \| "draft" \| "incomplete" \| "complete"	Optional	Only devices at this onboarding stage, as DeviceItem.setupStatus.
search	string	Optional	Case-insensitive text matched literally within the device's label, model or brand; must not be blank.

Example Request

curl -G "https://api.proxied.com/hoster/v1/devices" \
  -H "X-API-KEY: <api-key>" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Response Body

success
boolean
Always true on a successful response.
data
object
One page of the hoster's devices.
- items
  object[]
  This page's devices, newest first. One of the hoster's devices: what it is, its setup and use, and its IP rotation.
  - deviceId
    string
    The device's id, a 24-character hexadecimal string; the device routes take it as id.
  - model
    string | null
    The hardware model reported at registration; null on legacy devices.
  - brand
    string | null
    The hardware brand reported at registration; null on legacy devices.
  - label
    string | null
    The hoster's name for the device; null when it was never named.
  - setupStatus
    "awaiting_device_details" | "awaiting_agent" | "active" | "draft" | "incomplete" | "complete" | null
    The onboarding stage: awaiting_device_details (a managed device that has just enrolled), awaiting_agent (registered, but the agent app has not finished setup) or active (set up, which self-rent requires). draft, incomplete and complete are legacy devices, which cannot self-rent. Null only on legacy records without one.
  - appVersion
    string | null
    The version of the Proxied agent app on the device, as X.Y.Z; null until the agent reports.
  - lastHeartbeatAt
    string | null
    When the backend last heard from the device's agent app, as an ISO 8601 date-time; the time of its last message, not a live check. Null before its first report and on legacy devices.
  - rentalStatus
    "sold" | "self_rented" | "idle"
    Who uses the device: self_rented (the hoster holds a live self-rent rental, which wins over any listing), sold (a marketplace buyer holds it) or idle (neither).
  - marketplaceStatus
    "listed" | "not_listed"
    Whether the device is on the marketplace: listed (its current listing is buyable or bought) or not_listed (no listing, or one that is not on sale). Enabling self-rent takes it off.
  - selfRent
    object | null
    The hoster's live self-rent rental of the device; null when the hoster has none.
    - status
      "active" | "delinquent"
      active: paid up, and the hourly meter is billing. delinquent: an hourly charge failed for lack of funds; the tunnel keeps running for 12 hours and is then torn down, unless a later charge succeeds and makes it active again. While delinquent, setting rotation and the credential endpoints fail with 402.
    - rentalId
      string
      The rental's id, a 24-character hexadecimal string, as enabling self-rent returned it.
  - rotation
    object | null
    The device's scheduled IP rotation; null only when the device has no rotation setting.
    - status
      "active" | "disabled"
      active: the device toggles airplane mode every intervalInMs to get a new mobile IP; disabled: nothing is scheduled. Set through this API or by a marketplace buyer.
    - intervalInMs
      number
      Milliseconds between automatic rotations; kept while rotation is disabled.
- total
  number
  How many devices match the filters across all pages.
- page
  number
  The page number applied.
- limit
  number
  The page size applied.
- totalPages
  number
  How many pages the matches fill at this limit; 0 when nothing matches.

200 Response

{
  "success": true,
  "data": {
    "items": [
      {
        "deviceId": "68fb9f95c5c7c56bcf24d60f",
        "model": "Pixel 7",
        "brand": "google",
        "label": "Berlin-01",
        "setupStatus": "active",
        "appVersion": "6.8.6",
        "lastHeartbeatAt": "2026-10-21T09:15:42.123Z",
        "rentalStatus": "self_rented",
        "marketplaceStatus": "not_listed",
        "selfRent": {
          "status": "active",
          "rentalId": "6716a3f5c9e77b0012ab34c9"
        },
        "rotation": {
          "status": "active",
          "intervalInMs": 300000
        }
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Error Responses

Error shape

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "readable message"
  }
}

Status	Code	Description
400	VALIDATION_ERROR	Validation failed.
401	MISSING_API_KEY	Missing API key.
403	INVALID_API_KEY	Invalid key or suspended account.
403	HOSTER_BANNED	Invalid key or suspended account.
500	INTERNAL_ERROR	Internal error.