Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
version: 1.0.0
title: OmniServe Analytics Analytics Jobs API
description: "Complete API collection for Lucidya OmniServe Analytics Endpoints. This API provides access to \nanalytics data for engagement monitoring, CSAT surveys, and reporting capabilities.\n\nFeatures include:\n- Analytics pages and widgets discovery\n- Job-based analytics data retrieval\n- CSAT survey analytics\n- Reference data access (agents, teams, data sources)\n"
contact:
name: API Support
email: support@lucidya.com
url: https://lucidya.com
license:
url: https://opensource.org/licenses/MIT
name: MIT
servers:
- url: https://api.lucidya.com/public_api/omniserve
description: Production Server
security:
- OmniserveToken: []
tags:
- name: Analytics Jobs
description: Endpoints for creating and retrieving analytics jobs
paths:
/analytics/{page_name}/create:
post:
tags:
- Analytics Jobs
summary: Create Analytics Job
description: 'This endpoint enables you to create an analytics job for a page and returns a job_id for retrieving results.
'
operationId: createAnalyticsJob
parameters:
- name: page_name
in: path
description: Analytics page identifier
required: true
schema:
type: string
example: inbox
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
widgets_names:
type: array
description: Array of widget names to fetch
items:
type: string
example:
- Inbox Overview
- Engagements Volume
start_date:
type: integer
description: Unix timestamp for start date
format: int64
example: 1640995200
end_date:
type: integer
description: Unix timestamp for end date
format: int64
example: 1641081600
filters:
type: object
description: Filter object (optional)
example: {}
required:
- widgets_names
- start_date
- end_date
examples:
inboxFilters:
summary: Apply filters - inbox page
value:
widgets_names:
- Inbox Overview
- Engagements Volume
start_date: 1727395200
end_date: 1728000000
monitors: 101,102
filters:
data_sources: twitter,facebook
engagement_types: posts,direct_messages,emails
routings_ids: '5'
tags_ids: 10,12
exact_match: false
untagged_engagements: false
slasFilters:
summary: Apply filters - slas page
value:
widgets_names:
- SLAs Overview
- Breach Rate
start_date: 1727395200
end_date: 1728000000
monitors: '101'
filters:
data_sources: twitter
engagement_types: posts,direct_messages
slas_ids: 7,9
sla_type: time_to_complete,first_response_time,next_response_time,unassigned_response_time
tags_ids: 10,12
exact_match: false
untagged_engagements: false
agentsFilters:
summary: Apply filters - agents page
value:
widgets_names:
- Agents Performance
- Agents Workload
start_date: 1727395200
end_date: 1728000000
monitors: '101'
filters:
data_sources: facebook
engagement_types: posts,direct_messages
assignees_ids: 201,202
exact_match: false
untagged_engagements: false
application/x-www-form-urlencoded:
schema:
type: object
properties:
start_date:
type: integer
format: int64
example: 1760313600
end_date:
type: integer
format: int64
example: 1760918399
monitors:
type: string
description: Comma-separated monitor IDs
example: 45930,45922
filters:
type: string
description: URL-encoded JSON string of filters
example: '%7B%22data_sources%22:%22twitter,facebook,instagram,whatsapp,email,livechat%22,%22engagement_types%22:%22posts,direct_messages%22,%22routings_ids%22:%2256,57,62%22,%22tags_ids%22:%2218,2,1,21,28,27%22,%22exact_match%22:false,%22untagged_engagements%22:false%7D'
required:
- start_date
- end_date
examples:
rawConcatenated:
summary: Raw form-encoded body
value: product_id=10&start_date=1760313600&end_date=1760918399&monitors=45930,45922&filters=%7B%22data_sources%22:%22twitter,facebook,instagram,whatsapp,email,livechat%22,%22engagement_types%22:%22posts,direct_messages%22,%22routings_ids%22:%2256,57,62%22,%22tags_ids%22:%2218,2,1,21,28,27%22,%22exact_match%22:false,%22untagged_engagements%22:false%7D
responses:
'200':
description: Job created successfully
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
job_id:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
page_name:
type: string
example: inbox
widgets_names:
type: array
items:
type: string
example:
- Inbox Overview
- Engagements Volume
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'406':
$ref: '#/components/responses/NotAcceptable'
'410':
$ref: '#/components/responses/Gone'
'422':
$ref: '#/components/responses/ValidationFailed'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
'504':
$ref: '#/components/responses/GatewayTimeout'
security:
- OmniserveToken: []
servers:
- url: https://api.lucidya.com/public_api/omniserve
description: Production Server
/analytics/{page_name}/index:
get:
tags:
- Analytics Jobs
summary: Get Analytics Results
description: "This endpoint enables you to get the results of a previously created analytics job.\n\n## Response Structure\n\nThe response contains:\n- **dataAvailable**: Boolean indicating if all widget results are ready (true when complete)\n- **widget_data**: Object keyed by widget name, where each value is the widget's payload\n\n## Inbox Page Widgets\n\n### Inbox Overview\nAggregates counts per data source (twitter, twitter_dm, instagram, etc.):\n- **total_engagements**: Total found items in the period\n- **total_completed**: Count of completed engagements\n- **total_replied**: Count of replied engagements\n\n### Engagements Volume\n- **total_datasource_count**: Breakdown by engagement type (direct_message, comments_mentions, email_messages)\n- **engagements_overtime/posts_over_time**: Time-series data per source and engagement type\n\n### Agents Performance\n- **agents_performance**: Per-source array of agent performance objects containing:\n - agent_id: Agent identifier\n - assigned: Number of assigned engagements\n - completed: Number of completed engagements\n\n### Average SLAs\nContains current_period and previous_period data with aggregated sums and counts for:\n- **first_response_time**: Time to first agent response\n- **next_response_time**: Time between subsequent responses\n- **time_to_complete**: Total time to close the engagement\n- **unassigned_response_time**: Time spent unassigned (TUT)\n- **handling_time**: Calculated as time_to_complete - unassigned_response_time (for completed interactions only)\n\n### Data Sources\n- **data_source_distribution**: Total engagements per data source\n\n### Completion Reason\n- **completion_reasons**: Per-source arrays of completion reasons with:\n - id: Reason identifier\n - reason_en: Reason text in English\n - reason_ar: Reason text in Arabic\n - value: Count of engagements with this reason\n\n### Engagement Distribution Over Routings\nPer-source routing arrays containing:\n- routing_id: Routing identifier\n- value: Number of engagements\n\n### Tags Distribution Over Engagements\n- **tags_performance**: Arrays per source with tag label, color, and usage count\n\n### Tags Usage Over Time\n- **total_datasource_count**: Breakdown by engagement type\n- **engagement_tags_usage_overtime**: Time-series tag usage per source\n\n### Engagers Activity (Unique)\n- **result**: 2D heatmap matrix arrays showing activity distribution\n- **min_value/max_value**: Range of values in the heatmap\n\n### Engagements Completed Overtime\n- **total_datasource_count**: Total completed by engagement type\n- **completed_engagements_overtime**: Time-series of completed engagements\n\n### Engagements Completed By Teams\n- **engagements_completed_by_teams**: Per-source arrays with team_id and completion count\n\n---\n\n## SLAs Page Widgets\n\n### Average SLAs\nSame structure as Inbox page - contains current_period and previous_period aggregated sums and counts for all SLA metrics.\n\n### SLAs Overview\nHigh-level KPI summary:\n- **breach_rate_percentage**: Percentage of SLA breaches\n- **met_sla_count**: Total number of interactions that met SLA\n- **breached_sla_count**: Total number of SLA breaches\n\n### SLAs Time Distribution\nBucketed counts showing duration distribution (in minutes) for SLA metrics:\n- **time_to_complete**: Bucketed time ranges (e.g., 0-30, 31-60, 61-120, 121+)\n- **first_response_time**: Bucketed response times (e.g., 0-5, 6-15, 16+)\n- **next_response_time**: Bucketed time ranges\n- **unassigned_response_time**: Bucketed response times\n- **Note**: Time values are returned from APIs in seconds and need to be converted to minutes or hours\n\nEach bucket contains a label and value (count)\n\n### Average SLAs Overview\nPeriod averages (in minutes) for all SLA metrics:\n- first_response_time\n- next_response_time\n- time_to_complete\n- unassigned_response_time\n- handling_time\n\n### Hits Activity\nTime-series data of interactions that met SLA (hits):\n- **total_count**: Total hits in the period\n- **over_time**: Array of timestamp and count pairs\n\n### Misses Activity\nTime-series data of interactions that breached SLA (misses):\n- **total_count**: Total misses in the period\n- **over_time**: Array of timestamp and count pairs\n\n---\n\n## Agents Page Widgets\n\n### Overview\nHigh-level agent metrics per data source:\n- **total_assigned_engagements**: Total number of assigned engagements\n- **assigned_public_engagements**: Public engagements assigned count\n- **assigned_dm_engagements**: Direct message engagements assigned count\n- **assigned_email_engagements**: Email engagements assigned count\n- **manual_assigned_engagements**: Manually assigned engagement count\n- **auto_assigned_engagements**: Auto-assigned engagement count\n- **total_unique_contacts**: Number of unique contacts\n- **avg_engagements_per_contact**: Average engagements per contact\n\n### Agent Inbox Performance\nAgent performance metrics over time:\n- **agent_inbox_performance**: Per-source performance data\n - total_assigned: Total assigned to agents\n - posts_over_time: Time-series arrays for assigned and completed\n - total_completed: Total completed count\n- **agent_inbox_legends**: Summary legend with name-value pairs for assigned and completed\n\n### Agent CSAT Score Overtime\nCustomer satisfaction scores over time:\n- **csat_scores_overtime**: Per-source CSAT data\n - csat_scores_over_time: Array of date and scores (5-point scale array)\n - csat_scores_piechart: Distribution breakdown (e.g., csat_neutral, csat_positive, csat_negative)\n\n### Agents Performance\nIndividual agent performance metrics:\n- **agents_performance**: Per-source array of agent objects\n - agent_id: Agent identifier\n - assigned: Number of assigned engagements\n - completed: Number of completed engagements\n\n### Agents CSAT Score\nAgent-specific CSAT metrics per data source:\n- **data**: Object containing:\n - total_csat: Total CSAT score\n - scores: Array of score distributions (csat_neutral, csat_positive, csat_negative)\n\n### Agent Status Overview\nCurrent agent status distribution:\n- **data**: Array of status objects with:\n - status: Agent status (e.g., available, busy, offline)\n - total_sum: Count of agents in this status\n- **count**: Total number of agents\n\n### Agent Status Summary\nDetailed agent status information:\n- **data**: Array of agent status details\n\n### Agents Distribution\nDistribution of engagements across agents:\n- **engagement_distribution_over_agents**: Per-source distribution\n - total_engagements: Total engagement count\n - agents: Array of agent-specific distributions\n\n### Engagements Analytics\nComprehensive engagement analytics per data source:\n- **total_replied_engagements**: Count of replied engagements\n- **total_completed_engagements**: Count of completed engagements\n- **reopens**: Number of reopened engagements\n- **avg_handle_time**: Average handling time with value and count\n- **total_in_chat_survey_sent**: Number of in-chat surveys sent\n- **total_in_chat_survey_responses**: Number of survey responses received\n- **total_tags_on_engagements**: Total tags applied to engagements\n- **engagements_with_notes**: Count of engagements with notes\n"
parameters:
- name: job_id
in: query
description: Job identifier returned from the create job endpoint
required: true
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
- name: page_name
in: path
description: Analytics page identifier
required: true
schema:
type: string
example: inbox
responses:
'200':
description: Job results
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
dataAvailable:
type: boolean
description: Indicates whether all requested widgets finished processing; true when results are complete.
example: true
widget_data:
type: object
description: Map of widget name to its payload; each widget has its own structure (see example descriptions).
additionalProperties:
type: object
properties:
value:
type: number
description: Example KPI value for simple metric widgets; for complex widgets, see examples.
example: 150
trend:
type: string
description: Example trend direction for KPI widgets (e.g., up/down/flat).
example: up
percentage_change:
type: number
description: Example percentage change for KPI widgets.
example: 12.5
examples:
Inbox Job Results:
summary: Inbox page job results (condensed)
description: "Key meanings:\n- data: Top-level response wrapper.\n- dataAvailable: Boolean indicating if all widget results are ready.\n- widget_data: Object keyed by widget name; each value is the widget payload.\n- Inbox Overview: Aggregates counts per data source (e.g., twitter, twitter_dm, instagram)\n - total_engagements: Total found items in period\n - total_completed: Completed engagements count\n - total_replied: Replied engagements count\n- Engagements Volume:\n - total_datasource_count: Breakdown by engagement type (direct_message, comments_mentions, email_messages)\n - engagements_overtime/posts_over_time: Time-series per source and type\n- Agents Performance:\n - agents_performance: Per source array of agent performance objects { agent_id, assigned, completed }\n- Average SLAs:\n - current_period/previous_period: Aggregated sums and counts for SLA metrics (first_response_time, next_response_time, time_to_complete, unassigned_response_time, handling_time)\n - handling_time: Calculated as time_to_complete - unassigned_response_time (TUT), for completed interactions only\n- Data Sources:\n - data_source_distribution: Total engagements per source\n- Completion Reason:\n - completion_reasons: Per source arrays of reasons with { id, reason_en, reason_ar, value }\n- Engagement Distribution Over Routings:\n - per-source routings arrays with { routing_id, value }\n- Tags Distribution Over Engagements / Tags Usage Over Time:\n - tags_performance arrays and time-series usage per source\n- Engagers Activity (Unique):\n - result: 2D heatmap matrix arrays; min_value/max_value show range\n"
value:
data:
dataAvailable: true
widget_data:
Inbox Overview:
twitter_dm:
total_engagements: 79
total_completed: 64
total_replied: 38
twitter:
total_engagements: 119
total_completed: 29
total_replied: 55
instagram:
total_engagements: 77
total_completed: 27
Engagements Volume:
total_datasource_count:
- name: direct_message
value: 152
- name: comments_mentions
value: 215
- name: email_messages
value: 5
Agents Performance:
agents_performance:
twitter_dm:
- agent_id: 1341
assigned: 17
completed: 16
Average SLAs:
twitter_dm:
current_period:
first_response_time:
sum: 465343
count: 18
next_response_time:
sum: 1223
count: 3
time_to_complete:
sum: 1906072
count: 52
unassigned_response_time:
sum: 2143735
count: 61
handling_time:
sum: 156415
count: 51
previous_period:
first_response_time:
sum: 262023
count: 8
next_response_time:
sum: 50729817
count: 4
time_to_complete:
sum: 5281021
count: 48
unassigned_response_time:
sum: 4067691
count: 49
handling_time:
sum: 1213330
count: 48
Data Sources:
data_source_distribution:
twitter_dm:
total_engagements: 79
twitter:
total_engagements: 119
Engagement Distribution Over Routings:
engagement_distribution_over_routings:
twitter:
routings:
- routing_id: 62
value: 135
Tags Distribution Over Engagements:
tags_performance:
twitter_dm:
- label: Spam
color: '#FF3C2D'
value: 2
Tags Usage Over Time:
total_datasource_count:
- name: direct_message
value: 2
- name: comments_mentions
value: 1
engagement_tags_usage_overtime:
twitter_dm:
total_count: 2
posts_over_time:
direct_message:
- name: 1758412800
value: 1
Engagers Activity (Unique):
engager_activity:
instagram:
result:
- - 0
- 0
- 0
- - 1
- 0
- 0
max_value: 6
min_value: 0
Completion Reason:
completion_reasons:
twitter:
- id: 1
reason_en: REASON_EN_VALUE
reason_ar: REASON_AR_VALUE
value: 26
Engagements Completed Overtime:
total_datasource_count:
- name: direct_message
value: 124
- name: comments_mentions
value: 64
completed_engagements_overtime:
twitter_dm:
total_count: 64
posts_over_time:
direct_message:
- name: 1758412800
value: 12
Engagements Completed By Teams:
engagements_completed_by_teams:
twitter:
- team_id: 83
value: 15
twitter_dm:
- team_id: 83
value: 26
SLAs Job Results:
summary: SLAs page job results (condensed)
description: "Key meanings (SLAs page):\n- data: Top-level response wrapper\n- dataAvailable: True when all widget results are ready\n- widget_data: Object keyed by widget name; value is the widget payload\n- Average SLAs:\n - current_period/previous_period: Aggregated sums and counts for SLA metrics\n (first_response_time, next_response_time, time_to_complete, unassigned_response_time, handling_time)\n - handling_time: time_to_complete - unassigned_response_time (TUT), for completed interactions only\n- SLAs Overview: KPI summary such as met_sla_count, breached_sla_count, breach_rate_percentage\n- SLAs Time Distribution: Bucketed counts of durations (minutes) for SLA metrics (e.g., time_to_complete, first_response_time)\n- Average SLAs Overview: Period averages (minutes) for SLA metrics including handling_time\n- Hits Activity: Time-series of interactions that met SLA (hits)\n- Misses Activity: Time-series of interactions that breached SLA (misses)\n"
value:
data:
dataAvailable: true
widget_data:
Average SLAs:
twitter_dm:
current_period:
first_response_time:
sum: 465343
count: 18
next_response_time:
sum: 1223
count: 3
time_to_complete:
sum: 1906072
count: 52
unassigned_response_time:
sum: 2143735
count: 61
handling_time:
sum: 156415
count: 51
previous_period:
first_response_time:
sum: 262023
count: 8
next_response_time:
sum: 50729817
count: 4
time_to_complete:
sum: 5281021
count: 48
unassigned_response_time:
sum: 4067691
count: 49
handling_time:
sum: 1213330
count: 48
SLAs Overview:
breach_rate_percentage: 12.5
met_sla_count: 420
breached_sla_count: 60
SLAs Time Distribution:
time_distribution:
time_to_complete:
- label: 0-30
value: 120
- label: 31-60
value: 75
- label: 61-120
value: 40
- label: 121+
value: 18
first_response_time:
- label: 0-5
value: 210
- label: 6-15
value: 35
- label: 16+
value: 8
Average SLAs Overview:
description: Period averages for SLA metrics (in minutes).
averages:
first_response_time: 12.8
next_response_time: 7.5
time_to_complete: 85.4
unassigned_response_time: 34.2
handling_time: 51.2
Hits Activity:
description: Interactions that met SLA over time (hits)
hits_activity:
twitter_dm:
total_count: 40
over_time:
- name: 1758412800
value: 3
- name: 1758499200
value: 5
Misses Activity:
description: Interactions that breached SLA over time (misses)
misses_activity:
twitter_dm:
total_count: 12
over_time:
- name: 1758412800
value: 1
- name: 1758499200
value: 2
Agents Job Results:
summary: Agents page job results (condensed)
value:
data:
dataAvailable: true
widget_data:
Overview:
twitter_dm:
- total_assigned_engagements: 0
assigned_public_engagements: 0
assigned_dm_engagements: 0
assigned_email_engagements: 0
manual_assigned_engagements: 0
auto_assigned_engagements: 0
total_unique_contacts: 0
avg_engagements_per_contact: 0
Agent Inbox Performance:
agent_inbox_performance:
twitter_dm:
- total_assigned: 0
posts_over_time:
assigned: []
completed: []
total_completed: 0
agent_inbox_legends:
- name: assigned
value: 0
- name: completed
value: 0
Agent CSAT Score Overtime:
csat_scores_overtime:
twitter:
csat_scores_over_time:
- date: 1727319600
scores:
- 0
- 0
- 0
- 0
- 0
csat_scores_piechart:
- name: csat_neutral
value: 0
Agents Performance:
agents_performance:
twitter_dm:
- agent_id: 1341
assigned: 0
completed: 0
Agents CSAT Score:
twitter_dm:
- data:
total_csat: 0
scores:
- name: csat_neutral
value: 0
Agent Status Overview:
data:
- status: available
total_sum: 0
count: 21
Agent Status Summary:
data: []
Agents Distribution:
engagement_distribution_over_agents:
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lucidya-ltd/refs/heads/main/openapi/lucidya-ltd-analytics-jobs-api-openapi.yml