Calculate a conversation metric

Calculates an aggregate metric from conversation logs for the selected account and time range. Results can also include time buckets and, for eligible reseller accounts, organization or agent comparisons. Use the normal conversation logs endpoint to inspect the records behind a metric.

OpenAPI

````yaml post /api/v2/logs/timeSeries
openapi: 3.0.0
info:
version: 2.0.0
title: GetVoiceBot API
description: GetVoiceBot API Documentation
servers:
- url: https://api.getvoicebot.com
description: GetVoiceBot Production
variables:
baseUrl:
default: api.getvoicebot.com
description: Production API Root
security: []
tags:
- name: Agents
- name: Inbound Email
description: Control which senders may create inbound email work for an Agent.
- name: Features
description: Inspect capabilities available within an account hierarchy.
- name: Conversation Logs
description: Query conversation activity and calculate account-level metrics.
- name: Computer Agents
description: Set up, configure, inspect, and manage GetVoiceBot Computer Agents.
- name: Computer Agent Sessions
description: View and reset Computer Agent sessions.
- name: Accounts
- name: Agent Templates
description: Create, manage, and apply reusable Agent configurations.
paths:
/api/v2/logs/timeSeries:
post:
tags:
- Conversation Logs
summary: Calculate a conversation metric
description: >
Calculates an aggregate metric from conversation logs for the selected
account and time range. Results can also include time buckets and, for
eligible reseller accounts, organization or agent comparisons. Use the
normal conversation logs endpoint to inspect the records behind a
metric.
operationId: timeSeriesPostIndex
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- definition
- startAt
- endAt
- targetAccountId
properties:
targetAccountId:
type: integer
description: >-
Account whose authorized conversation data should be
analyzed.
startAt:
type: integer
description: Inclusive start of the range as Unix seconds.
endAt:
type: integer
description: >-
Inclusive end of the range as Unix seconds. Must be after
startAt.
definition:
type: object
required:
- formula
- aggregation
description: >-
Metric calculation applied to each matching conversation
log.
properties:
formula:
type: string
minLength: 1
maxLength: 2000
description: >
Numeric expression to aggregate. It may reference log
fields and use arithmetic, comparisons, boolean
operators, IF, NOW, TIMESTAMP_DIFF, ABS, MIN, MAX, SUM,
AVG, COUNT, D_COUNT, MED, VARIANCE, or STD_DEV.
example: transfer == true
aggregation:
type: object
required:
- type
properties:
type:
type: string
enum:
- sum
- avg
- count
- d_count
- med
- variance
- std_dev
description: How matching formula values are combined.
term:
type: string
enum:
- minutes
- hours
- days
- weeks
- months
description: Time bucket used when time-series data is requested.
filters:
type: object
additionalProperties: true
description: >
Conversation-log fields that limit the source records.
Append operators such as __gte, __lte, __in, __contains,
or __isnull to a field name when needed.
fieldTypes:
type: object
additionalProperties:
type: string
enum:
- number
- boolean
- truthy
- string
description: Value types for custom fields referenced by the formula.
minimumSampleSize:
type: integer
minimum: 1
description: >-
Hide metric values for groups or buckets with fewer
matching records.
includeTimeSeries:
type: boolean
default: true
description: Include metric values grouped into time buckets.
groupBy:
type: string
enum:
- none
- organization
- agent
description: >
Add ranked group results. Organization and agent grouping
are available when the selected account has access to those
account levels.
scope:
type: object
required:
- type
properties:
type:
type: string
enum:
- allOrganizations
- selectedOrganizations
organizationIds:
type: array
maxItems: 500
items:
type: integer
minimum: 1
description: Organization subset used for reseller-level grouped metrics.
search:
type: string
maxLength: 100
description: Match organization or agent names in grouped results.
sort:
type: string
enum:
- metricValue
- eventCount
default: metricValue
description: Field used to order grouped results.
direction:
type: string
enum:
- asc
- desc
default: desc
description: Sort direction for grouped results.
page:
type: integer
minimum: 1
default: 1
description: Group-result page number.
pageSize:
type: integer
minimum: 1
maximum: 100
default: 25
description: Number of grouped results per page.
refresh:
type: boolean
default: false
description: Recalculate instead of using a recent identical result.
responses:
'200':
description: Metric calculated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
aggregate:
type: number
nullable: true
description: Metric value across every matching conversation.
metricTotal:
type: number
description: Sum used to calculate the aggregate.
eventCount:
type: integer
minimum: 0
description: Number of matching conversation records.
minimumSampleSize:
type: integer
minimum: 1
description: Requested minimum sample size, when supplied.
qualified:
type: boolean
description: >-
Whether the aggregate meets the requested minimum sample
size.
timeSeries:
type: object
additionalProperties:
type: number
nullable: true
description: Metric values keyed by Unix-second bucket start.
timeSeriesEventCounts:
type: object
additionalProperties:
type: integer
minimum: 0
description: >-
Matching record counts by bucket when a minimum sample
size is used.
groups:
type: array
description: Organization or agent comparisons when groupBy is enabled.
items:
type: object
properties:
organizationId:
type: integer
organizationName:
type: string
agentId:
type: integer
agentName:
type: string
metricValue:
type: number
nullable: true
metricTotal:
type: number
eventCount:
type: integer
minimum: 0
pagination:
type: object
description: Present when grouped results are requested.
properties:
page:
type: integer
pageSize:
type: integer
totalCount:
type: integer
totalPages:
type: integer
'400':
description: The metric definition, scope, or time range is invalid
'504':
description: The metric could not be calculated within the allowed time
security:
- apiKeyAuth: []
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: query
name: token
description: GetVoiceBot API Token

````

Open the app All docs