Reports
Group, filter and sort
Three optional parameters shape a report before it reaches you: group_by turns totals into one row per week or month, filter.<field> keeps only the rows you need, and sort orders them. They combine with every other parameter, and a feed writes them for you.
Totals per week or per month
/reports/agents normally gives one row per agent for the whole period. With group_by=week you get one row per agent per ISO week (Monday to Sunday); with group_by=month, one row per agent per calendar month. This is the layout of weekly production feeds such as WIP.
GET /api/v1/reports/agents?activity=AC-0006&month=2026-10&group_by=week
&fields=agent_code,week,period_start,period_end,monday,tuesday,wednesday,thursday,friday,saturday,sunday,paid_time{
"data": [
{
"agent_code": "AG-0042",
"week": "2026-W42",
"period_start": "2026-10-12",
"period_end": "2026-10-18",
"monday": 7.5,
"tuesday": 7.5,
"wednesday": 7.5,
"thursday": 7.5,
"friday": 7.5,
"saturday": 0,
"sunday": 0,
"paid_time": 37.5
}
],
"meta": {
"type": "agents",
"group_by": "week",
"day_value": "paid_time",
"filters": [],
"sort": "agent_code,week",
"count": 1,
"total": 64,
"limit": 500,
"next_cursor": null
}
}- Grouped rows add the columns week (2026-W42) or month (2026-10), plus period_start and period_end. Every totals column (paid_time, days_worked, contract_gap…) is computed for that week or month.
- Weekly rows also have monday, tuesday … sunday. Each holds that day's paid time by default; day_value picks another daily duration: paid_time, shift_time, productive_time, break_paid, break_unpaid, lunch_time, coffee_time, meeting_time, night_time, time_off_paid, time_off_unpaid.
- Weeks and months at the edges of the period are cut to it. Asking for October grouped by week gives a first row from Thursday 1 to Sunday 4: monday to wednesday are null (outside the period), and contract_target counts those four days only.
- Every agent of the activity gets a row for every week or month, even with nothing scheduled, so a missing row always means a missing agent.
Filters
Add filter.<field>=value to keep only the rows that match. A suffix after the field picks another test. Up to 20 filters per request.
| Parameter | Keeps rows where the value… | Example |
|---|---|---|
filter.<field>=a,b | is one of the values. Text ignores upper and lower case. | filter.agent_code=AG-0001,AG-0002 |
filter.<field>.not=a,b | is none of the values. Empty values are kept. | filter.live_status.not=planned |
filter.<field>.gt=x | is more than x. Numbers, durations, dates and times. | filter.start_delta.gt=0 |
filter.<field>.gte=x | is x or more. | filter.paid_time.gte=7.5 |
filter.<field>.lt=x | is less than x. | filter.first_start.lt=08:00 |
filter.<field>.lte=x | is x or less. | filter.date.lte=2026-10-15 |
filter.<field>.empty=true|false | is empty (true) or filled (false). | filter.cf.matricule.empty=true |
- Every filter must hold. To accept several values for one column, list them in one filter, separated by commas.
- Any column of the report type can be filtered, whether or not it is in fields. Custom fields work too: filter.cf.site=Cotonou.
- Write values the way the response writes them: dates 2026-10-12, times 08:30, booleans true or false. Durations follow the durations parameter (7.5 hours by default, 450 with durations=minutes), and h:mm such as 7:30 always works.
- Filters test the rows as returned: on grouped rows they test the week's or month's totals, so filter.paid_time.gt=40&group_by=week keeps agent-weeks above 40 hours.
- The same access rules as columns apply: filtering on personal data needs personal details access, and on live columns needs source=live.
A filter the API can't apply is refused with invalid_parameter, and param names the exact filter:
{
"error": {
"code": "invalid_parameter",
"message": "filter.paid_time.gte: durations are in decimal hours here (7.5), or h:mm (7:30).",
"param": "filter.paid_time.gte",
"request_id": "9b2f0c1e-5d43-4f7a-8a61-0c2b3e4d5f60"
}
}Sorting
sort lists up to 5 columns, comma-separated. A - in front sorts that column from highest to lowest. Any column of the report type can be used, returned or not.
GET /api/v1/reports/shifts?activity=AC-0006&week=2026-W42&source=live
&filter.start_delta.gt=0&sort=-start_delta,agent_code- Without sort, rows come by agent, then in time order, activity by activity.
- Empty values always come last, in both directions. Rows that tie keep the default order.
- Sorting happens before paging, so next_cursor continues the same order. Keep the same sort for every page of one read.