Get counters by product
This endpoint allows querying the counter data of a product for a period not exceeding 366 days. Assignments or consolidated clockguards will be considered for the calculation, depending on the configuration.
GET /api/v2/businesses/{businessId}/products/{productId}/counters-with-clockguards?businessCounterIds={id}&from={yyyy-MM-dd}&to={yyyy-MM-dd}|
The identifiers to be used in the URL ( |
If the request is correct, the response will contain the counter data specified in the URL.
Response example
GET /api/v2/businesses/BUSINESSID/products/PRODUCTID/counters-with-clockguards?businessCounterIds=4035&from=2026-08-18&to=2026-08-21[
{
"counter": {
"id": 4035,
"counterType": {
"id": 1,
"key": "counter.weekly_net_hours",
"shortName": "HNS",
"scope": "WEEK",
"dataType": "TIME"
},
"customName": "Net hours",
"customShortName": "HN"
},
"counts": [
{
"key": "HNS_HN_20260817_20260823",
"from": "2026-08-17",
"to": "2026-08-23",
"total": [
{
"employeeId": "1006350",
"count": 360.0,
"dailyCount": [
{
"day": "2026-08-19",
"count": 120
},
{
"day": "2026-08-18",
"count": 240
}
]
},
{
"employeeId": "170326",
"count": 0.0,
"dailyCount": []
}
]
}
]
}
]Details
-
counter: counter information.
-
id: identifier of the Business Counter (link between the business and the counter type).
-
counterType: counter type information.
-
id: internal identifier of the counter type.
-
key: counter type key defined internally.
-
shortName: abbreviation of the counter type.
-
scope: temporal scope of the counter (
WEEK,MONTH,YEAR, etc.). -
dataType: data type of the counter (
TIME,INTEGER, etc.).
-
-
customName: custom name of the counter, present only if a custom configuration has been defined.
-
customShortName: custom abbreviation of the counter, present only if a custom abbreviation has been defined.
-
-
counts: list of periods with the counter values.
-
key: key identifying the calculation period.
-
from: start date of the calculation period.
-
to: end date of the calculation period.
-
total: list of values per employee in the period.
-
employeeId: external identifier of the employee.
-
count: counter value for the indicated period.
-
dailyCount: daily breakdown of the counter value for the employee. If there are no values, an empty array
[]will appear.-
day: date the value corresponds to.
-
count: counter value for that day.
-
-
-
In this example, the counter shows the weekly net hours worked by each employee, expressed in minutes.
Considerations
This query takes both assignments and consolidated clockguards into account, but does not add them together. For each day of the requested period, the system chooses a single source: the consolidated clockguard or the planned assignment.
The choice depends, first, on the service parameter Compute counters with clockguards:
-
If it is disabled, counters are always computed with assignments.
-
If it is enabled (default behavior), counters are computed with consolidated clockguards based on the effective clockguard range.
The effective clockguard range is the date range within which the system treats already consolidated clockguards as valid. The behavior is as follows:
-
If the day falls within the range, the clockguard is used (if there is no clockguard, it counts
0, even if there is an assignment). -
If the day falls outside the range, the assignment is used.
|
The range is always capped at yesterday, so today’s clockguard is never included in the effective range, even if it is the most recently recorded one: that day falls outside the range and is computed using the assignment. |
To set the range, the business parameter Count all clockguards is used, which determines when clockguards start being counted:
-
Disabled (default): the range extends up to the Sunday of the week prior to the week of the last recorded clockguard, capped at yesterday. The week of the last clockguard is excluded, in case it is not yet fully consolidated.
-
Enabled: the range extends up to the date of the last recorded clockguard, capped at yesterday. Clockguards for the current week are counted.
|
The range limit is always calculated from the date of the last recorded clockguard, not from the current date: recording a more recent clockguard shifts that limit, although the week of the last clockguard will still be excluded under the default configuration. |
The response will depend on the counter’s configuration, such as its scope (weekly, monthly, yearly, etc.) or its data type (minutes, number of days, etc.).
Data for multiple counters can be retrieved in the same request by including different identifiers in the URL, separated by commas: ?businessCounterIds=id1,id2,….
If there is no data affecting the counter for the period specified in the URL, it will display "count": 0.0.
Employees who do not have an external identifier configured in the system (employeeId) will appear in the response without this field.
Error codes
In addition to the common errors, this endpoint can return the following codes:
| Code | Message | Description |
|---|---|---|
- |
No value present |
One of the identifiers indicated in |
|
The request exceded the maximum number of days allowed (366 days max) |
The requested period between |