Skip to main content

List Devices

Discover the devices your API key can access with GET /v5/devices — query parameters, response fields, organization filtering, pagination, and the expand option.

List Devices COMING SOON!

GET /v5/devices

Returns a list of every device the authenticated API key can access — so you can discover device IDs without knowing any of them in advance. Use this endpoint to build a device picker, or to gather the device_id values you'll pass to other v5 endpoints (for example, when pulling readings with Get Device Readings).

The list reflects your memberships: it includes devices from organizations you belong to as well as devices shared with you through individual projects. You can optionally scope the list to a single organization, page through large result sets, and opt in to each device's first and last measurement dates.

Authentication

Authenticated with your API key in the X-API-Key header; the user is resolved from the key. See Authentication in the Overview.

Request

GET https://api.zentracloud.io/v5/devices

Query parameters

Parameter

Type

Required

Default

Description

organization_id

string (UUID)

No

-

Restricts the list to a single organization. If omitted, the response includes devices across every organization and project you can access. See Filtering by organization below.

page_num

integer

No

1

The page of results to return. 1-indexed; must be ≥ 1.

limit

integer

No

50

The maximum number of devices per page. Must be between 1 and 1000.

expand

string

No

-

Attaches extra data to each device. Repeatable (e.g. expand=max_min_timestamp). Currently max_min_timestamp is the only supported value. See The The expand parameter below.

Example requests

Basic list:

curl "https://api.zentracloud.io/v5/devices" \
  -H "X-API-Key: YOUR_API_KEY"

Filter to one organization:

curl "https://api.zentracloud.io/v5/devices?organization_id=c042f395-8466-459b-8b61-7b26557851da" \
  -H "X-API-Key: YOUR_API_KEY"

Request a second page of 100 devices:

curl "https://api.zentracloud.io/v5/devices?page_num=2&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

Include each device's measurement range:

curl "https://api.zentracloud.io/v5/devices?expand=max_min_timestamp" \
  -H "X-API-Key: YOUR_API_KEY"

Response

A 200 OK response contains a devices array and a pagination object.

devices[]

Each item represents one device. Devices are ordered by device ID (serial number) ascending.

Field

Type

Description

device_id

string

The unique identifier (serial) for the device. Use this value when calling other v5 endpoints.

name

string

The device's display name. When no custom name has been set, this defaults to the device_id.

organization_id

string (UUID)

The organization the device belongs to.

data_range

object

Present only when expand=max_min_timestamp is requested. Contains first_measurement and last_measurement, each a Unix timestamp (seconds since the epoch, UTC) or null. See The expand parameter below.

pagination

Field

Type

Description

page_num

integer

The page number you requested. The response always echoes the requested page.

limit

integer

The maximum number of devices per page.

num_devices

integer

The number of devices returned on this page.

total_pages

integer

The total number of pages available for your full accessible set at the current limit.

Note: num_devices is the count for the current page, not a total across all pages. The endpoint does not return an exact total device count; use total_pages to iterate.

Example response

{
  "devices": [
    {
      "device_id": "A4100001",
      "name": "A4100001",
      "organization_id": "c042f395-8466-459b-8b61-7b26557851da"
    },
    {
      "device_id": "A4100002",
      "name": "Butterriver",
      "organization_id": "c042f395-8466-459b-8b61-7b26557851da"
    },
    {
      "device_id": "z6-16514",
      "name": "Oakriver",
      "organization_id": "c042f395-8466-459b-8b61-7b26557851da"
    }
    // ... additional devices omitted for brevity
  ],
  "pagination": {
    "page_num": 1,
    "limit": 50,
    "num_devices": 13,
    "total_pages": 1
  }
}

Empty result

If your memberships grant access to no devices (or no devices in a filtered organization), the response is still 200 with an empty array and a valid pagination block:

{
  "devices": [],
  "pagination": {
    "page_num": 1,
    "limit": 50,
    "num_devices": 0,
    "total_pages": 0
  }
}

Filtering by organization

Pass organization_id to restrict the list to a single organization.

  • If you are a member of that organization, the response is 200 and every returned device belongs to it.
  • If you have only project-level access in that organization (no full-organization membership), the response is still 200, restricted to the devices shared with you through your project(s) there. Project access counts as membership.
  • If you are not a member of the organization at all, the response is 403 Forbidden — never a silently empty 200. This lets you distinguish "you don't have access" from "you have access, but there are no devices."

Pagination

The list is paginated with page_num and limit, ordered by device ID ascending across your entire accessible set. Because the ordering is stable, iterating page_num=1, 2, 3, … at a fixed limit neither skips nor repeats devices.

  • page_num is 1-indexed and defaults to 1.
  • limit defaults to 50 and can be set from 1 to 1000.
  • Requesting page_num below 1, limit below 1, or limit above 1000 returns 422 before any device lookup runs.
  • To page through everything, start at page_num=1 and continue until you reach total_pages.

The expand parameter

By default the response contains only the base device fields. Add expand=max_min_timestamp to attach a data_range object to each device describing when it first and last produced a measurement. first_measurement and last_measurement are Unix timestamps — whole seconds since the epoch, in UTC:

{
  "devices": [
    {
      "device_id": "z6-12345",
      "name": "Riverbend",
      "organization_id": "c042f395-8466-459b-8b61-7b26557851da",
      "data_range": {
        "first_measurement": 1643390100,
        "last_measurement": 1783462500
      }
    },
    {
      "device_id": "z6-12346",
      "name": "Riverdrive",
      "organization_id": "c042f395-8466-459b-8b61-7b26557851da",
      "data_range": {
        "first_measurement": 1643745600,
        "last_measurement": 1783467000
      }
    },
    {
      "device_id": "z6-12347",
      "name": "Riverfront",
      "organization_id": "c042f395-8466-459b-8b61-7b26557851da",
      "data_range": {
        "first_measurement": null,
        "last_measurement": null
      }
    }
  ],
  "pagination": {
    "page_num": 1,
    "limit": 50,
    "num_devices": 3,
    "total_pages": 1
  }
}

  • Timestamps are seconds since the Unix epoch (UTC). For example, 1643390100 is January 28, 2022 at 17:15 UTC.
  • A device that has never produced a measurement returns data_range with both values null.
  • When expand is not supplied, data_range is omitted from every device and no range computation is performed.
  • expand is repeatable: ?expand=max_min_timestamp (and, in a future release, additional values).
  • Passing an unrecognized expand value returns 422 and identifies the offending value.

Rate limiting

Rate limited per user; requests beyond your limit return 429. See Rate Limiting.

Errors

Status

Endpoint-specific cause

403

Passing an organization_id you have no membership in.

433

page_num < 1, limit outside 1–1000, or an unrecognized expand value.

See Errors for the full model, including 401 and 429.

Notes

  • Results are scoped to your memberships, so the same request made by two different users can return different devices.
  • device_id is the value to carry into other v5 API calls; name is for display only and may change.

How did we do?

Errors

Get Device Readings

Contact