Retrieving Scheduled Hours Using the Assembled API

Assembled provides several API endpoints you can use to retrieve scheduled hours and adherence data. Based on their specific needs, teams often use this data for external reporting, workforce analytics, payroll calculations, or reporting on agents scheduled hours.

Depending on the level of detail you need, you can retrieve detailed schedule events, aggregated schedule metrics, or recurring working-hours patterns. This guide walks through the three approaches and potential use cases for each one.

In this article:

• How do I retrieve detailed schedule events?
• How do I retrieve aggregated adherence metrics?
• How do I retrieve working hours patterns?

How do I retrieve detailed schedule events?

To get detailed schedule events for agents over a specific time period, use the GET /v0/activities endpoint. This endpoint returns activity records that represent planned schedule events assigned to individual agents—like work blocks, breaks, lunches, or time-off events. These activities are the building blocks of an agent's planned schedule.

When to use this approach

Use this endpoint when you need detailed planned schedule data for agents rather than aggregated schedule or adherence metrics.

Required fields

• start_time — The start of the time range to query activities for. Must be provided as a Unix timestamp (seconds since epoch).
• end_time — The end of the time range to query activities for. Must also be provided as a Unix timestamp.

Optional fields you might need

• include_activity_types — When set to true, the response includes the associated activity_type_id values with the activity records. To translate those IDs into readable activity type names or categories, you'll need to make a separate request to GET /v0/activity_types.
• include_agents — When set to true, the response includes the associated agent objects. This can help when mapping activity records back to employees in another system.
• team — Filters activities to those associated with a specific team. This can help narrow the results to a particular operational group.
• channel — Filters activities by channel (for example, phone, chat, or email work). Useful if only certain types of work activity are relevant for reporting or analysis.
• types — Filters results to specific activity types. This can be used if only certain types of schedule events are relevant (for example, productive work or time-off events).
• agents — Filters the response to activities belonging to specific agent IDs. This is helpful if the results should only include a defined group of agents.
• return_full_schedule — When set to true, returns all schedule events including overlapping events. The default behavior returns only the effective events (only the event in the highest layer at any moment, which is ideal for reporting and metrics calculations).

API documentation

For example requests and responses, see the GET activities API reference and the Activity types API reference.

How do I retrieve aggregated adherence metrics?

To get summarized time totals and adherence-related metrics instead of individual schedule events, use the Reports API. The adherence report provides metrics for agents over a specified time range, showing how closely agents followed their planned schedules. These metrics combine schedule data and agent state data and are grouped by agent and time interval, showing agents’ actual time vs. scheduled time at the aggregate level.

When to use this approach

Use this endpoint when you need aggregated metrics—like scheduled time, worked time, and adherence percentages—rather than detailed event records.

How the reporting process works

Reports are generated asynchronously, meaning the request and retrieval happen in two steps:

1. POST /v0/reports/adherence to request generation of the report
2. GET /v0/reports/{reportId} to retrieve the completed report using the returned report ID

Once the report is available, the response contains metric records for each agent within the requested time window.

Required fields

• start_time — The beginning of the reporting window. Must be provided as a Unix timestamp in UTC.
• end_time — The end of the reporting window. Must also be provided as a Unix timestamp in UTC.
• interval — The time interval used to group results. Common values include 1h, 24h, or 1w.
• channel — Specifies the channel the report should be generated for (for example, voice, chat, or email).

Optional fields you might need

• metric — When retrieving the report, this query parameter can be used to return only specific metrics rather than the full metric set.

Key metrics returned

• scheduled_seconds — Total amount of time an agent was scheduled to work during the specified time period.
• actual_seconds_worked — Total amount of time the agent actually worked during the specified time period.
• actual_seconds_in_adherence — Total time the agent worked while following their scheduled events.
• adherence_percentage — Percentage of scheduled time during which the agent followed their schedule.
• schedule_adherence_percentage — Percentage of scheduled events that the agent adhered to during the reporting period.

API documentation

For example requests and responses, see the Adherence report API reference, Retrieve report API reference, and Report adherence documentation.

How do I retrieve working hours patterns?

To review recurring working-hour patterns instead of actual schedule events, use the GET /v0/scheduling_rules/working_hours endpoint. This endpoint returns a list of working hours rules configured in Assembled. These rules represent recurring patterns that define when agents are expected to work, and they typically include information like start and end times, the days of the week the rule applies to, and the assignment groups associated with the rule.

When to use this approach

Use this endpoint when you need to review the recurring working-hours configuration rather than detailed schedule events assigned to a person on a specific day.

What's the difference between activities and working hours?

Activities represent actual planned event blocks on an agent's schedule for a specific time window (for example, work, breaks, or time off). Working hours represent the recurring patterns or rules used as scheduling inputs or constraints.

Important note about availability

Assembled is transitioning from Shift Patterns to Working Hours. If you're currently using Shift Patterns, this endpoint won't work until the migration is complete. Assembled provides a Shift Patterns endpoint, which will soon be deprecated. We recommend waiting until the migration is complete to use the Working Hours endpoint rather than integrating with Shift Patterns.

For more context, see What are working hours? and How do scheduling rules work?

Required fields

None. A GET request will return all working hours rules available in your account.

Key fields in the response

• id — Unique identifier for the working hours rule.
• name — Name of the working hours rule.
• location — Timezone associated with the working hours rule.
• start_day_of_week — Indicates which day the working hours cycle begins on.
• days — Defines the working hours for each day within the rule.
• assignment_groups — Specifies which agents, sites, teams, queues, or skills the working hours rule applies to.

API documentation

For example requests and responses, see the Working hours API reference.