Advanced Jomioz API: Pagination, Filtering, and Bulk Ops

Once your basic integration is working, these advanced API patterns help you handle large datasets efficiently, reduce unnecessary network overhead, and perform high-volume operations in fewer round-trips. This guide covers cursor-based pagination, field and metadata filtering, sorting, bulk operations, and practical tips for squeezing the most performance out of your integration.

Pagination

The Jomioz API uses cursor-based pagination for all list endpoints. Unlike offset-based pagination, cursor-based pagination stays consistent even when new records are inserted between pages — making it the right choice for real-time or frequently updated datasets.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	`20`	Number of records to return per page. Maximum is `200`.
`cursor`	string	—	Opaque cursor pointing to the start of the next page. Omit on the first request.

Example

curl "https://api.jomioz.com/v1/api/resources?limit=50&cursor=cur_8fnq2mwb3xkp" \
  -H "Authorization: Bearer $JOMIOZ_API_KEY"

const params = new URLSearchParams({ limit: "50", cursor: "cur_8fnq2mwb3xkp" });
const response = await fetch(
  `${process.env.JOMIOZ_BASE_URL}/api/resources?${params}`,
  { headers: { Authorization: `Bearer ${process.env.JOMIOZ_API_KEY}` } }
);
const data = await response.json();

The response includes a pagination object. When next_cursor is null, you have reached the last page.

{
  "data": [
    { "id": "res_01hx3kpq7bnf9z2t4m6vw8cde", "name": "Sensor A", "status": "active" },
    { "id": "res_02jy4lqr8cpg0a3u5n7xb9def", "name": "Sensor B", "status": "inactive" }
  ],
  "pagination": {
    "total": 312,
    "limit": 50,
    "next_cursor": "cur_9gor3nxc4ylq"
  }
}

Pass next_cursor as the cursor parameter in your next request to retrieve the following page. Continue until next_cursor is null.

Filtering Resources

Narrow list results by appending filter parameters to the query string. Filters are additive — all supplied conditions must match (logical AND).

Common Filter Parameters

Parameter	Example value	Description
`status`	`active`	Return only resources with the given status.
`type`	`sensor`	Return only resources of the given type.
`created_after`	`2024-01-01T00:00:00Z`	Return resources created after this ISO 8601 timestamp.
`created_before`	`2024-06-01T00:00:00Z`	Return resources created before this ISO 8601 timestamp.

Example

curl "https://api.jomioz.com/v1/api/resources?status=active&type=sensor" \
  -H "Authorization: Bearer $JOMIOZ_API_KEY"

const params = new URLSearchParams({ status: "active", type: "sensor" });
const response = await fetch(
  `${process.env.JOMIOZ_BASE_URL}/api/resources?${params}`,
  { headers: { Authorization: `Bearer ${process.env.JOMIOZ_API_KEY}` } }
);
const { data } = await response.json();

Sorting

Control the order of list results with the sort and order parameters.

Parameter	Values	Default
`sort`	`created_at`, `updated_at`, `name`	`created_at`
`order`	`asc`, `desc`	`desc`

Example

curl "https://api.jomioz.com/v1/api/resources?sort=created_at&order=desc" \
  -H "Authorization: Bearer $JOMIOZ_API_KEY"

const params = new URLSearchParams({ sort: "created_at", order: "desc" });
const response = await fetch(
  `${process.env.JOMIOZ_BASE_URL}/api/resources?${params}`,
  { headers: { Authorization: `Bearer ${process.env.JOMIOZ_API_KEY}` } }
);
const { data } = await response.json();

Combine sorting with filtering and pagination in a single request — all query parameters work together.

Bulk Operations

Use the bulk endpoint to create, update, or delete multiple resources in a single HTTP request. This reduces latency and helps you stay within rate limits (1,000 req/min on Standard; 5,000 req/min on Enterprise) when processing large datasets. Send a POST request to /api/resources/bulk with a JSON array in the body. Each element follows the same schema as the single-resource POST /api/resources endpoint.

Example — Bulk Create

curl -X POST https://api.jomioz.com/v1/api/resources/bulk \
  -H "Authorization: Bearer $JOMIOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Sensor Alpha",
      "type": "sensor",
      "status": "active",
      "metadata": { "zone": "north" }
    },
    {
      "name": "Sensor Beta",
      "type": "sensor",
      "status": "active",
      "metadata": { "zone": "south" }
    },
    {
      "name": "Actuator Gamma",
      "type": "actuator",
      "status": "inactive",
      "metadata": { "zone": "east" }
    }
  ]'

const resources = [
  { name: "Sensor Alpha",   type: "sensor",   status: "active",   metadata: { zone: "north" } },
  { name: "Sensor Beta",    type: "sensor",   status: "active",   metadata: { zone: "south" } },
  { name: "Actuator Gamma", type: "actuator", status: "inactive", metadata: { zone: "east"  } },
];

const response = await fetch(`${process.env.JOMIOZ_BASE_URL}/api/resources/bulk`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JOMIOZ_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(resources),
});

const result = await response.json();

The response contains a results array where each element corresponds to the input item at the same index. Individual items that fail validation return an error object rather than a resource object — the rest of the batch still succeeds.

{
  "results": [
    { "id": "res_11aa1bb1cc1d", "name": "Sensor Alpha",   "status": "active"   },
    { "id": "res_22ee2ff2gg2h", "name": "Sensor Beta",    "status": "active"   },
    { "id": "res_33ii3jj3kk3l", "name": "Actuator Gamma", "status": "inactive" }
  ],
  "summary": {
    "total": 3,
    "succeeded": 3,
    "failed": 0
  }
}

The bulk endpoint accepts a maximum of 200 items per request. If your payload exceeds this limit, split it into multiple requests and process them sequentially or in parallel, respecting your plan’s rate limit.

Metadata Filtering

Every resource supports a free-form metadata object that you can use to store arbitrary key-value pairs. Filter resources by metadata values using bracket notation in query parameters.

Example

curl "https://api.jomioz.com/v1/api/resources?metadata[env]=production&metadata[zone]=north" \
  -H "Authorization: Bearer $JOMIOZ_API_KEY"

// URLSearchParams does not support bracket notation natively,
// so build the query string manually or use a helper library.
const query = "metadata[env]=production&metadata[zone]=north";
const response = await fetch(
  `${process.env.JOMIOZ_BASE_URL}/api/resources?${query}`,
  { headers: { Authorization: `Bearer ${process.env.JOMIOZ_API_KEY}` } }
);
const { data } = await response.json();

You can combine metadata filters with any other filter, sort, or pagination parameter in the same request.

Metadata values are indexed as strings. Numeric comparisons (greater than, less than) are not supported through the metadata filter interface. If you need range queries, store those values as top-level resource fields instead.

Performance Tips

Request only the fields your application needs by appending ?fields=id,name,status to any list or get request. Sparse fieldsets reduce payload size, lower serialisation overhead on both sides, and make your integration more resilient to future additions to the resource schema.

curl "https://api.jomioz.com/v1/api/resources?fields=id,name,status&limit=200" \
  -H "Authorization: Bearer $JOMIOZ_API_KEY"

const params = new URLSearchParams({ fields: "id,name,status", limit: "200" });
const response = await fetch(
  `${process.env.JOMIOZ_BASE_URL}/api/resources?${params}`,
  { headers: { Authorization: `Bearer ${process.env.JOMIOZ_API_KEY}` } }
);
const { data } = await response.json();

Additional performance recommendations:

Maximise page size. Set limit=200 when you need to fetch a full dataset — fewer HTTP round-trips means faster total execution time.
Cache stable data. Resource objects that do not change frequently (for example, type and metadata) can be cached locally and refreshed periodically rather than fetched on every request.
Use webhooks instead of polling. Subscribe to relevant event types via webhook to receive instant notifications instead of repeatedly calling list endpoints.
Parallelise independent requests. If your workflow requires data from multiple unrelated endpoints, issue the requests concurrently rather than sequentially.
Upgrade to Enterprise for higher rate limits. Standard accounts are capped at 1,000 req/min; Enterprise accounts have a 5,000 req/min limit, which is essential for high-volume ingestion pipelines.

Get Started

Core Concepts

Guides

Integrations

Support

Advanced Jomioz API: Pagination, Filtering, and Bulk Ops

Query Parameters

Example

Filtering Resources

Common Filter Parameters

Example

Sorting

Example

Bulk Operations

Example — Bulk Create

Metadata Filtering

Example

Performance Tips

​Pagination

​Query Parameters

​Example

​Filtering Resources

​Common Filter Parameters

​Example

​Sorting

​Example

​Bulk Operations

​Example — Bulk Create

​Metadata Filtering

​Example

​Performance Tips

Pagination

Query Parameters

Example

Filtering Resources

Common Filter Parameters

Example

Sorting

Example

Bulk Operations

Example — Bulk Create

Metadata Filtering

Example

Performance Tips