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
analytics data for engagement monitoring, CSAT surveys, and reporting capabilities.
Features include:
- Analytics pages and widgets discovery
- Job-based analytics data retrieval
- CSAT survey analytics
- Reference data access (agents, teams, data sources)'
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.
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:
twitter:
- total_engagements: 0
agents: []
Engagements Analytics:
twitter_dm:
- total_replied_engagements: 0
total_completed_engagements: 0
reopens: 0
avg_handle_time:
value: 0
count: 0
total_in_chat_survey_sent: 0
total_in_chat_survey_responses: 0
total_tags_on_engagements: 0
engagements_with_notes: 0
'202':
description: Processing (if applicable)
'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
operationId: getAnalyticsByPageNameIndex
x-operation-id-source: derived
components:
responses:
MethodNotAllowed:
description: Method Not Allowed - HTTP method is not supported for this endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 405
message: Method not allowed
Gone:
description: Gone - the requested resource is no longer available
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 410
message: Resource gone
BadRequest:
description: Bad request - invalid input or validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 400
detail: Page_id is required
Unauthorized:
description: Unauthorized - invalid or missing authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 401
message: Authentication required
RateLimited:
description: Too many requests - rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 429
message: Rate limit exceeded
retry_after: 60
ServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 500
message: Internal server error
GatewayTimeout:
description: Gateway Timeout - server took too long to respond
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 504
message: Gateway timeout
Forbidden:
description: Forbidden - insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 403
message: Access denied
NotAcceptable:
description: Not Acceptable - the requested format is not supported
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 406
message: Not acceptable
NotFound:
description: Not Found - the specified resource could not be found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 404
message: Resource not found
ServiceUnavailable:
description: Service Unavailable - temporary server overload or maintenance
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 503
message: Service unavailable
ValidationFailed:
description: Unprocessable Entity - validation failed or missing required fields
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
default:
value:
status: 422
message: Validation failed
schemas:
Error:
type: object
properties:
error:
type: object
properties:
status:
type: integer
example: 400
detail:
type: string
example: Page_id is required
status:
type: integer
example: 400
message:
type: string
example: Error message
code:
type: string
example: ERROR_CODE
securitySchemes:
OmniserveToken:
type: apiKey
description: The API authorization token for the request
name: luc-authorization
in: header
x-example: YOUR_API_TOKEN_HERE