Aiklyra documentations

Conversation Flow Analysis

Analyzes the flow of conversations by clustering utterances into intents and constructing a conversational graph.
Base URL:
API Prefix:
This API enables you to submit conversation data for asynchronous analysis and retrieve the analysis results later. The analysis is processed using Celery tasks, and each submitted job is assigned a unique job ID.

Endpoints Overview

POST
Submits conversation data for analysis (returns job ID).
/conversation-flow-analysis/analyse-conversation
GET
Retrieves the status and result of an analysis job.
/conversation-flow-analysis/job-status/{job_id}

1. Submit Conversation Analysis

Endpoint
Submits a conversation analysis job for asynchronous processing. The API validates the request, filters conversation data by role (if specified), and enqueues the analysis task. On success, it returns a unique job_id.
Request Headers
Content-Type
application/json
Indicates that the request body is JSON.
accept
application/json
Informs the server that JSON responses are expected.
Request Body
The request body must be a JSON object conforming to the BaseConversationFlowAnalysisRequest schema. The table below describes each field:
conversation_data
object
required
A dictionary where each key represents a conversation ID, and the value

min_cluster
integer
default: 5
Minimum number of clusters to create during analysis
max_cluster
integer
default: 10
Maximum number of clusters to create during analysis
top_k_nearest_to_centroid
integer
default: 10
Maximum number of clusters to create during analysis
role
string
default: "Any"
Filters utterances by role (e.g., "user" , "agent" ). "Any" includes all roles
Successful Response
On a successful submission, the API returns a JSON response matching the JobSubmissionResponse schema:
job_id
string
A unique identifier for the submitted job.
1curl -X POST "https://api.aiklyra.com/conversation-flow-analysis/analyse-conversation"      -H "Content-Type: application/json"      -H "accept: application/json"      -d '{
2           "conversation_data": {
3             "conversation_1": [
4               {"role": "user", "content": "Hello, how are you?"},
5               {"role": "assistant", "content": "I am fine, thank you!"}
6             ],
7             "conversation_2": [
8               {"role": "user", "content": "Can you help me with my order?"},
9               {"role": "assistant", "content": "Sure, please provide your order ID."}
10             ]
11           },
12           "min_clusters": 5,
13           "max_clusters": 10,
14           "top_k_nearest_to_centroid": 10,
15           "role": "Any"
16         }'
1{
2  "job_id": "job_12345"
3}

2. Get Job Status

Endpoint
Retrieves the current status and result (if available) of a previously submitted analysis job. The API checks the status of the Celery task and returns additional details.
Request Headers
Content-Type
application/json
Indicates JSON is being used.
accept
application/json
Informs the server that JSON responses are expected.
Response Body
The response conforms to the JobStatusResponse schema. The table below outlines the fields:
job_id
string
The unique job ID.
status
string
The status of the job. Possible values are: PENDING, STARTED, SUCCESS, FAILURE, RETRY, REVOKED.
estimated_wait_time
integer
optional
Estimated wait time (in seconds) if the job is still pending.
result
object
optional
The analysis result when the job is complete. See below for the structure of the result.

error
string
optional
Minimum number of clusters to create during analysis
Analysis Result (Nested in result)
The result field is a JSON object following the ConversationFlowAnalysisResponse schema:
transition_matrix
array of arrays
A 2D array (matrix) representing transition probabilities.
intent_by_cluster
object (dictionary)
A mapping from integer cluster IDs to intent descriptions.
1curl -X GET "https://api.aiklyra.com/conversation-flow-analysis/job-status/job_12345"      -H "accept: application/json"
1{
2  "job_id": "job_12345",
3  "status": "completed",
4  "estimated_wait_time": 0,
5  "result": {
6    "transition_matrix": [
7      [0.5, 0.5],
8      [0.0, 0.0]
9    ],
10    "intent_by_cluster": {
11      "0": "Greeting and establishing rapport",
12      "1": "Response to Greeting"
13    }
14  },
15  "error": null
16}

Task Status Definitions

The API (via Celery) can return several task statuses. Below is a table summarizing each status:
PENDING
string
The task is waiting for execution.
STARTED
string
The task has started execution.
SUCCESS
string
The task has completed successfully.
FAILURE
string
The task has failed.
RETRY
string
The task is being retried.
REVOKED
string
The task has been revoked.

Summary

Submit Analysis:
Use the POST /conversation-flow-analysis/analyse-conversation endpoint to submit conversation data. You will receive a job_id which uniquely identifies the analysis job.
Check Job Status:
Use the GET /conversation-flow-analysis/job-status/{job_id} endpoint with the returned job_id to retrieve the job status. If the job is complete, the response will include the analysis result.
Task Status:
The API uses a variety of task statuses (e.g., PENDING, STARTED, SUCCESS, FAILURE, RETRY, REVOKED) to indicate the state of your analysis job.
For further integration details or troubleshooting, please refer to our complete API reference or contact our support team.