---
title: "Calls Timeline Data"
method: POST
path: "/analytics/calls/v1/accounts/{accountId}/timeline/fetch"
tags: ["Business Analytics"]
---

# Calls Timeline Data

`POST /analytics/calls/v1/accounts/{accountId}/timeline/fetch`

Returns time-value data aggregations filtered by parameters specified

## Path parameters

- `accountId` string, required

## Query parameters

- `interval` 'Hour' | 'Day' | 'Week' | 'Month', required
- `page` integer
- `perPage` integer

## Request body

- TimelineRequest
  - `grouping` union, required — This field specifies the dimensions by which the response should be grouped and specific keys to narrow the response. See also [Call Aggregate reports](https://developers.ringcentral.com/guide/analytics/aggregate) or [Call Timeline reports](https://developers.ringcentral.com/guide/analytics/timeline) pages in the developer guide for more information
    - DirectGrouping — This grouping allows to specify the `groupBy` option by which the data in the response will be grouped
      - `groupBy` 'Company' | 'CompanyNumbers' | 'Users' | 'Queues' | 'IVRs' | 'SharedLines' | 'UserGroups' | 'Sites' | 'Departments', required — The selected grouping option
      - `keys` string[] — This field can be used to specify unique identifiers of entities selected in `groupBy` field. The response data will be limited to these entities only
    - GroupingByMembers — This grouping allows to specify the `groupByMembers` option. The response data will be grouped by users and will only include users that belong to the scope selected in `groupByMembers` field
      - `groupByMembers` 'Department' | 'UserGroup' | 'Queue' | 'Site', required — The selected data scope
      - `keys` string[] — This field can be used to further limit the users selection by specifying unique identifiers of corresponding entities. For example, providing unique queue ids along with `Queue` in `groupByMembers` field will limit the response to users that are queue agents in at least one of these queues
  - `timeSettings` TimeSettings, required — Date-time range for the calls. The call is considered to be within time range if it started within time range. Both borders are inclusive
    - `timeZone` string, required — Name of the timezone that will be used for `includeDays` and `includeHours` filters and aggregation intervals. For example 'America/Los_Angeles', 'Europe/Zurich'. See also *[Time Zones](https://www.iana.org/time-zones)*. Value in this field doesn't affect interpretation of time in `timeRange`, as it already includes offset from UTC
    - `timeRange` TimeRange, required — Time range for the request
      - `timeFrom` string, date-time, required — The start date-time for resulting records in RFC 3339 format including offset between local time and UTC, for example 2016-03-15T18:07:52.534Z
      - `timeTo` string, date-time, required — The end date-time for resulting records in RFC 3339 format including offset between local time and UTC, for example 2016-03-15T18:07:52.534Z
    - `advancedTimeSettings` AdvancedTimeSettings — Allows more granular control over time included in the report
      - `includeDays` DayOfWeek[] — Days of the week for which the report is calculated
      - `includeHours` HoursInterval[] — Hours of the day for which the report is calculated
        - `from` string, required — Time in format hh:mm
        - `to` string, required — Time in format hh:mm
  - `callFilters` CallFilters — Optional filters that limit the scope of calls (joined via AND)
    - `extensionFilters` ExtensionFilters — Specifies filtering based on extension ids
      - `fromIds` string[] — List of extension ids to match against incoming calls, joined via OR condition. Only applicable for `groupByMembers` options and Users, IVRs, SharedLines and Queues in `groupBy`
      - `toIds` string[] — List of extension ids to match against outgoing calls, joined via OR condition. Limited to the extension id that first accepted the call. Only applicable for `groupByMembers` options and Users, IVRs and SharedLines in `groupBy`
    - `queues` string[] — List of queues extension ids which allows to get data only for calls that were routed through any of these queues
    - `calledNumbers` string[] — The direct company numbers the caller called (joined via OR)
    - `directions` Direction[] — Specifies the call directions relative to the scope specified in grouping object (joined via OR). Not applicable to internal origin calls with company scope
    - `origins` Origin[] — Specifies whether an external party was present in the initial segment of the call (joined via OR)
    - `callResponses` CallResponse[] — Filtering of calls by first response (joined via OR)
    - `callResults` CallResult[] — Filtering of calls by the nature of call result (joined via OR)
    - `callSegments` CallSegmentFilter[] — Filtering of calls by presence of specific segment (joined via OR)
      - `segment` 'Ringing' | 'LiveTalk' | 'Hold' | 'Park' | 'Transfer' | 'IvrPrompt' | 'Voicemail' | 'VmGreeting' | 'Setup', required — Call segment for filtering
      - `length` CallSegmentLengthFilter — Duration bounds for the segment
        - `minSeconds` integer — Minimum duration of segment in seconds
        - `maxSeconds` integer — Maximum duration of segment in seconds
    - `callActions` CallAction[] — Filtering of calls by presence of specific action (joined via OR)
    - `companyHours` CompanyHoursOptions[] — Filtering of calls by company's business hours or after hours (joined via OR)
    - `callDuration` CallDurationFilter — Filtering of calls based on the overall call length
      - `minSeconds` integer — Minimum duration of call in seconds
      - `maxSeconds` integer — Maximum duration of call in seconds
    - `timeSpent` TimeSpentFilter — Filtering of calls based on the time spent by specified mailbox(es) on call
      - `minSeconds` integer — Minimum duration in seconds
      - `maxSeconds` integer — Maximum duration in seconds
    - `queueSla` QueueSlaOptions[] — Filtering calls that were within or out of queue SLA (joined via OR). Only applicable to Queues grouping
    - `callTypes` CallType[] — Filtering of calls based on how the call started from the callee perspective (joined via OR). If the call is outbound relative to the grouping scope, CallType is Outbound
  - `responseOptions` TimelineResponseOptions, required — Counters and timers options for calls breakdown
    - `counters` TimelineResponseOptionsCounters — Options for selecting breakdown for calls count
      - `allCalls` boolean — Include data for total calls count
      - `callsByDirection` boolean — Include breakdown of calls count by direction (Inbound, Outbound)
      - `callsByOrigin` boolean — Include breakdown of calls count by origin (Internal, External)
      - `callsByResponse` boolean — Include breakdown of calls count by response (Answered, NotAnswered, Connected, NotConnected)
      - `callsSegments` boolean — Include breakdown of calls count by segments (Ringing, LiveTalk, Hold, Park, Transfer, IvrPrompt, Voicemail, VmGreeting, Setup)
      - `callsByResult` boolean — Include breakdown of calls count by result (Completed, Abandoned, Voicemail, Unknown, Missed, Accepted)
      - `callsByCompanyHours` boolean — Include breakdown of calls count by company hours (BusinessHours, AfterHours)
      - `callsByQueueSla` boolean — Include breakdown of calls count by queue SLA (InSLA, OutSLA). This counter is only applicable to Queues grouping
      - `callsByActions` boolean — Include breakdown of calls count by action (HoldOff, HoldOn, ParkOn, ParkOff, BlindTransfer, WarmTransfer, DTMFTransfer)
      - `callsByType` boolean — Include breakdown of calls count by type (Direct, FromQueue, ParkRetrieval, Transferred, Outbound)
      - `queueOpportunities` boolean — Include breakdown of calls count by the total number of times a Queue call was presented to the user. It is limited to `groupBy` Users and `groupByMembers` (Department, Queue, Site, UserGroup) grouping. Only the listed below options for call filters are applicable to `queueOpportunities` and provide meaningful results: `queues` (selected queue extension ids), `callResults` (Missed, Abandoned), `callResponses` (Answered, NotAnswered), `origins` (Internal, External)
    - `timers` TimelineResponseOptionsTimers — Options for selecting breakdown for calls duration
      - `allCallsDuration` boolean — Include data for all calls duration
      - `callsDurationByDirection` boolean — Include breakdown of calls duration by direction (Inbound, Outbound)
      - `callsDurationByOrigin` boolean — Include breakdown of calls duration by origin (Internal, External)
      - `callsDurationByResponse` boolean — Include breakdown of calls duration by response (Answered, NotAnswered, Connected, NotConnected)
      - `callsSegmentsDuration` boolean — Include breakdown of calls duration by segments (Ringing, LiveTalk, Hold, Park, Transfer, IvrPrompt, Voicemail, VmGreeting, Setup)
      - `callsDurationByResult` boolean — Include breakdown of calls duration by result (Completed, Abandoned, Voicemail, Unknown, Missed, Accepted)
      - `callsDurationByCompanyHours` boolean — Include breakdown of calls duration by company hours (BusinessHours, AfterHours)
      - `callsDurationByQueueSla` boolean — Include breakdown of calls duration by queue SLA (InSLA, OutSLA). This timer is only applicable to Queues grouping
      - `callsDurationByType` boolean — Include breakdown of calls duration by type (Direct, FromQueue, ParkRetrieval, Transferred, Outbound)

## Response `200`

Calls Timeline

- TimelineResponse
  - `paging` ResponsePaging, required — Paging information
    - `page` integer, required — The current page number
    - `perPage` integer, required — How many items are displayed on the page
    - `totalPages` integer, required — The total number of pages
    - `totalElements` integer, required — The total number of items in the dataset
  - `data` TimelineResponseData, required — A list of time-value points of call data as per the grouping and filtering options specified in the request
    - `groupedBy` 'Company' | 'CompanyNumbers' | 'Users' | 'Queues' | 'IVRs' | 'SharedLines' | 'UserGroups' | 'Sites' | 'Departments', required — The selected grouping option
    - `records` TimelineResponseRecord[] — List of call data as per the grouping and filtering options specified in the request
      - `key` string, required — Grouping key
      - `info` KeyInfo — Additional info about the key
        - `extensionNumber` string — Extension's number
        - `name` string — Extension's name
      - `points` TimelineResponsePoint[] — List of requested call data time-value points
        - `time` string, date-time, required — Time point in RFC 3339 format
        - `timers` CallsTimers — Call length data for the specified grouping
          - `allCalls` AllCalls — Data for all calls
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` number, double, required — Value for all calls
          - `callsByDirection` CallsByDirection — Data for calls with breakdown by direction (Inbound, Outbound)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByDirectionBreakdown, required — Result breakdown by direction
              - …
          - `callsByOrigin` CallsByOrigin — Data for calls with breakdown by origin (Internal, External)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByOriginBreakdown, required — Result breakdown by origin
              - …
          - `callsByResponse` CallsByResponse — Data for calls with breakdown by response (Answered, NotAnswered, Connected, NotConnected)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByResponseBreakdown, required — Result breakdown by response
              - …
          - `callsSegments` CallsBySegments — Data for calls with breakdown by segments (Ringing, LiveTalk, Hold, Park, Transfer, IvrPrompt, Voicemail, VmGreeting, Setup)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsBySegmentsBreakdown, required — Result breakdown by segments
              - …
          - `callsByResult` CallsByResult — Data for calls with breakdown by result (Completed, Abandoned, Voicemail, Unknown, Missed, Accepted)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByResultBreakdown, required — Result breakdown by call result
              - …
          - `callsByCompanyHours` CallsByCompanyHours — Data for calls with breakdown by company hours (BusinessHours, AfterHours)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByCompanyHoursBreakdown, required — Result breakdown by company hours
              - …
          - `callsByQueueSla` CallsByQueueSla — Data for calls with breakdown by queue SLA (InSLA, OutSLA). This counter is only applicable to Queues grouping
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByQueueSlaBreakdown, required — Result breakdown by queue SLA
              - …
          - `callsByType` CallsByType — Data for calls with breakdown by type (Direct, FromQueue, ParkRetrieval, Transferred, Outbound, Overflow)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByTypeBreakdown, required — Result breakdown by type
              - …
        - `counters` CallsCounters — Call volume data for the specified grouping
          - `allCalls` AllCalls — Data for all calls
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` number, double, required — Value for all calls
          - `callsByDirection` CallsByDirection — Data for calls with breakdown by direction (Inbound, Outbound)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByDirectionBreakdown, required — Result breakdown by direction
              - …
          - `callsByOrigin` CallsByOrigin — Data for calls with breakdown by origin (Internal, External)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByOriginBreakdown, required — Result breakdown by origin
              - …
          - `callsByResponse` CallsByResponse — Data for calls with breakdown by response (Answered, NotAnswered, Connected, NotConnected)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByResponseBreakdown, required — Result breakdown by response
              - …
          - `callsSegments` CallsBySegments — Data for calls with breakdown by segments (Ringing, LiveTalk, Hold, Park, Transfer, IvrPrompt, Voicemail, VmGreeting, Setup)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsBySegmentsBreakdown, required — Result breakdown by segments
              - …
          - `callsByResult` CallsByResult — Data for calls with breakdown by result (Completed, Abandoned, Voicemail, Unknown, Missed, Accepted)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByResultBreakdown, required — Result breakdown by call result
              - …
          - `callsActions` CallsByActions — Data for calls with breakdown by action (HoldOff, HoldOn, ParkOn, ParkOff, BlindTransfer, WarmTransfer, DTMFTransfer)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByActionsBreakdown, required — Result breakdown by actions
              - …
          - `callsByCompanyHours` CallsByCompanyHours — Data for calls with breakdown by company hours (BusinessHours, AfterHours)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByCompanyHoursBreakdown, required — Result breakdown by company hours
              - …
          - `callsByQueueSla` CallsByQueueSla — Data for calls with breakdown by queue SLA (InSLA, OutSLA). This counter is only applicable to Queues grouping
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByQueueSlaBreakdown, required — Result breakdown by queue SLA
              - …
          - `callsByType` CallsByType — Data for calls with breakdown by type (Direct, FromQueue, ParkRetrieval, Transferred, Outbound, Overflow)
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` CallsByTypeBreakdown, required — Result breakdown by type
              - …
          - `queueOpportunities` QueueOpportunities — Queue opportunities data for the specified grouping
            - `valueType` 'Percent' | 'Seconds' | 'Instances', required — Unit of the result value
            - `values` number, double, required — Value for queue opportunities

## Other responses

- `400` — General response with **HTTP 400 "Bad request"** status.<br> Reasons: unparsable request, path, query or body parameters are invalid. The error description may contain reference to particular parameter(s) which haven't passed the validation.
- `401` — General response with **HTTP 401 "Unauthorized"** status.<br> Reasons: user authentication failed.
- `403` — General response with **HTTP 403 "Forbidden"** status.<br> Reasons: the requested operation is forbidden because of certain resource state, lack of permissions, feature unavailability, etc.
- `500` — General response with **HTTP 500 "Internal Server Error"** status.<br> Reasons: general server-side error.

---

[API](https://skmtc.net/ringcentral/apis/ringcentral-api.md) · [All operations](https://skmtc.net/ringcentral/apis/ringcentral-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ringcentral/ringcentral-api/revisions/8d602198ec97/schema)