Skip to main content

Pagination, Filtering & Dates

This section explains how to use common pagination, search, filtering and date parameters across Homsai endpoints.

Overview​

Many Homsai endpoints share the same conventions for:

  • pagination of lists (plants, devices, sensors, types, load signatures, etc.);
  • search and filters (search, UUIDs, view modes);
  • time ranges and granularity for history and energy metrics.

Understanding these patterns lets you reuse the same approach across most APIs.

Pagination​

Endpoints that return lists (e.g. GET /plants, GET /plants/{plantUuid}/devices, GET /sensor-types, GET /load-signatures) typically support pagination with:

  • page: page index (zero‑based, e.g. 0, 1, 2…).
  • size: number of items per page.
  • sort: field(s) to sort by, optionally with direction (e.g. name,asc or createdAt,desc).

Example:

GET /plants?page=0&size=20&sort=name,asc
Authorization: Bearer <accessToken>

The response usually follows a Spring‑style pattern (or equivalent), with:

  • the array of items (e.g. content or data);
  • current page info (page number, size);
  • total counts (e.g. totalElements, totalPages).

Search & filtering​

Many endpoints expose filter parameters to narrow down results.

Common examples:

  • search: generic text filter (by name, description or other indexed fields).
  • plantUuids: list of plant UUIDs to include (on GET /plants).
  • externalIds: list of external identifiers (on GET /plants).
  • dataTypesCollectUuid: filter by collected data type (on GET /plants/{plantUuid}/sensors).
  • mode: for logical view modes, for example:
    • GET /plants/{plantUuid}/vendors?mode=config (configured vendors),
    • GET /plants/{plantUuid}/vendors?mode=not_config (not yet configured vendors).
  • includeRelationships: flag to include additional relational data (e.g. sensors linked to a device).

Examples:

GET /plants?search=rossi&size=10

GET /plants/{plantUuid}/devices?search=inverter&includeRelationships=true

GET /plants/{plantUuid}/sensors?dataTypesCollectUuid=<uuid>&page=0&size=50

GET /plants/{plantUuid}/vendors?mode=config

Combining pagination + filters lets you query large plants with many devices and sensors efficiently.

Dates & time ranges​

Endpoints dealing with history and energy metrics use consistent date formats.

Most common formats:

  • Simple date (day)

    • yyyy-MM-dd
    • Example: 2025-01-15
    • Used, for example, in:
      • GET /plants/{plantUuid}/daily-power-consumptions?date=2025-01-15
      • GET /plants/{plantUuid}/daily-power-productions?date=2025-01-15

  • Date and time (timestamp)

    • yyyy-MM-dd'T'HH:mm
    • Example: 2025-01-15T13:30
    • Used to define ranges in:
      • GET /plants/{plantUuid}/sensor-history-consumptions
      • GET /plants/{plantUuid}/sensor-history-productions
      • GET /plants/{plantUuid}/sensor-history-energy

Typical parameters:

  • startDate: range start (required in several endpoints).
  • endDate: range end (often optional).
  • date: reference day (for endpoints working on relative windows like “last 7 days” or “last 24 hours”).

Examples:

GET /plants/{plantUuid}/summary-daily-power-consumptions?startDate=2025-01-01&endDate=2025-01-31

GET /plants/{plantUuid}/sensor-history-consumptions?startDate=2025-01-01T00:00&endDate=2025-01-07T23:59&granularity=hours

Data granularity​

For some history APIs, you can control the granularity of returned data:

  • parameter: granularity
  • supported values:
    • seconds
    • minutes
    • hours
    • days

Examples:

  • granularity=seconds: returns near‑raw points (highest available resolution).
  • granularity=hours: aggregates data hourly.
  • granularity=days: aggregates data daily.

This parameter is used, for example, in:

  • GET /plants/{plantUuid}/sensor-history-consumptions
  • GET /plants/{plantUuid}/sensor-history-productions

Choose the granularity based on your use case:

  • real‑time dashboards → seconds or minutes;
  • daily/hourly charts → hours;
  • monthly reports or long‑term comparisons → days.