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.

ParameterKeeps rows where the value…Example
filter.<field>=a,bis one of the values. Text ignores upper and lower case.filter.agent_code=AG-0001,AG-0002
filter.<field>.not=a,bis none of the values. Empty values are kept.filter.live_status.not=planned
filter.<field>.gt=xis more than x. Numbers, durations, dates and times.filter.start_delta.gt=0
filter.<field>.gte=xis x or more.filter.paid_time.gte=7.5
filter.<field>.lt=xis less than x.filter.first_start.lt=08:00
filter.<field>.lte=xis x or less.filter.date.lte=2026-10-15
filter.<field>.empty=true|falseis 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.
Group, filter and sort — Planifizer API docs