> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/en/api-reference/ping-gu-he-ce-shi-ji.md).
# Evaluations and Test Sets
The evaluation and test set endpoints correspond to "Test Sets" and "Automated Testing" in the AgentOps back office, letting you batch-test Agents from your own systems. The full flow is:
1. **Create a test set**: Use `POST /api/v1/dataset/` to create an empty test set, or use `POST /api/v1/dataset/upload/` to upload a CSV/Excel file and create one in a single step.
2. **Add test cases**: For single-turn Q\&A, use `/api/v1/test-case/` (create one by one, upload a file, or generate from a knowledge base file); for multi-turn conversation scenarios, use `/api/v1/multi-turn-test-case/`. Generating from a knowledge base file runs in the background and returns `202` with a `jobId`; track it with [Retrieve test case generation job progress](#test-case-generation-jobs-retrieve).
3. **Run an evaluation**: Use `POST /api/v1/evaluations/evaluate/` (single-turn) or `POST /api/v1/evaluations/multi-turn-evaluate/` (multi-turn) to specify the test set and Agent. The response is `202` with an `evaluationId`.
4. **Read results and export**: Poll `GET /api/v1/evaluations/{id}/` until `status` becomes `completed`, `partial_completed`, or `failed`. Per-question results for single-turn evaluations are in `details`, and per-conversation results for multi-turn evaluations are in `multi-turn-results`. A completed single-turn evaluation can be exported as an Excel report with `export`, and the download URL is available from `export-status`.
**Required permissions**: The API Key calls the API as the member who created it. Listing and all write operations on `/dataset/`, `/test-case/`, and `/multi-turn-test-case/` require a role with the "Test Set permission"; listing and all write operations on `/evaluations/` require the "Automated Testing permission" (the AgentOps permissions in [Role Permissions](https://docs.maiagent.ai/org/roles/role-permission); owners always have them). Insufficient permissions return `403`. Members other than the owner can only see and evaluate Agents that their role is allowed to use.
**Credit**: Generating test cases from knowledge base files deducts the pricing item `agentops_test_gen` based on the number of questions actually generated. Running an evaluation deducts `agentops_test_run` and `agentops_deepeval` when it finishes, based on the number of completed test cases, and the evaluation model calls used for scoring are billed separately according to that model's usage. Before a generation or evaluation request is submitted, the system checks the organization's Credit and quota, and returns `402` if they are insufficient. Manual creation, file upload, and reading results do not deduct Credit; for unit prices, see [List pricing items](/api/en/api-reference/credit.md#credit-items-list).
For features and back-office operations, see the user manual pages [Test Set Management](https://docs.maiagent.ai/build/agent-ops/test-datasets) and [Automated Evaluation and Agent Monitoring](https://docs.maiagent.ai/build/agent-ops/evaluations).
### List Test Sets
GET `/api/v1/dataset/`
#### Parameters
| Parameter | Required | Type | Description |
| ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isActive` | ❌ | boolean | List only active (true) or inactive (false) datasets |
| `ordering` | ❌ | string | Sort field: created\_at or updated\_at. Prefix with - for newest first (e.g. -updated\_at). If not specified, sorted by creation time, newest first |
| `page` | ❌ | integer | Page number, starting from 1. Returns 404 if beyond the last page |
| `pageSize` | ❌ | integer | Number of items per page. Default 20, maximum 100 (values above 100 are treated as 100) |
| `query` | ❌ | string | Keyword; matches the dataset name, description, or ID (partial match) |
| `search` | ❌ | string | Keyword; matches the dataset name or description (partial, case-insensitive match; when multiple keywords are separated by spaces, all must match) |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example", config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"name": string
"description"?: string // Optional
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // Optional
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**Example Response Values**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "Response string",
"updatedAt": "Response string"
}
]
}
```
***
### Create an empty test set
POST `/api/v1/dataset/`
{% hint style="info" %}
Test set names must be unique within an organization; a duplicate name returns `400`.
{% endhint %}
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| ----------- | ------ | -------- | ----------- |
| name | string | Yes | |
| description | string | No | |
**Example Request Structure**
```typescript
{
"name": string
"description"?: string // Optional
}
```
**Example Request Values**
```json
{
"name": "Example name",
"description": "Example string"
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/dataset/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example name",
"description": "Example string"
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request body (payload)
const data = {
"name": "Example name",
"description": "Example string"
};
axios.post("https://api.maiagent.ai/api/v1/dataset/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"name": "Example name",
"description": "Example string"
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/dataset/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => 'Example name',
'description' => 'Example string'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 201**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // Optional
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // Optional
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Upload CSV or Excel to create a test set
POST `/api/v1/dataset/upload/`
{% hint style="info" %}
Upload as `multipart/form-data`: `file` and `name` are required, and `description` is optional. The file format is the same as [Upload CSV or Excel to add test cases](#test-case-upload-create); test set names must be unique within an organization.
{% endhint %}
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/dataset/upload/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-F "file=@example_file.csv" \
-F "name=Example string" \
-F "description=Example string"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
const FormData = require('form-data');
// Create a FormData object
const formData = new FormData();
// Replace with the actual file
formData.append('file', /* actual file object */, 'example_file.csv');
formData.append('name', 'Example string');
formData.append('description', 'Example string');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
...formData.getHeaders()
}
};
axios.post("https://api.maiagent.ai/api/v1/dataset/upload/", formData, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/upload/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
# Create the file and form data
files = {
'file': ('example_file.csv', open('example_file.csv', 'rb'), 'text/csv'),
'name': (None, 'Example string'),
'description': (None, 'Example string')
}
response = requests.post(url, files=files, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/dataset/upload/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
],
'multipart' => [
[
'name' => 'file',
'contents' => fopen('example_file.csv', 'r'),
'filename' => 'example_file.csv'
],
[
'name' => 'name',
'contents' => 'Example string'
],
[
'name' => 'description',
'contents' => 'Example string'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 201**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // Optional
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // Optional
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Generate a test set from a knowledge base file
POST `/api/v1/dataset/generate-from-file/`
{% hint style="info" %}
Creates a new test set from a single knowledge base file (`knowledgeBaseFileId`) and generates single-turn test cases; `numTestCases` ranges from 1 to 50 (default 10). Generation runs in the background, and the actual response is `202` with a `taskId`; it does not include the test set ID, and there is no progress to query. Once generation finishes, the new test set appears in the list. If you need to track progress, first create an empty test set and then use [Generate single-turn test cases from a knowledge base file](#test-case-generate-from-file-create). **Credit**: The organization's Credit is checked before submission, and `402` is returned if it is insufficient; `agentops_test_gen` is deducted based on the number of questions actually generated.
{% endhint %}
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| ------------------- | ------------- | -------- | ----------- |
| name | string | Yes | |
| description | string | No | |
| chatbotFileId | string (uuid) | No | |
| knowledgeBaseFileId | string (uuid) | No | |
| numTestCases | integer | No | |
**Example Request Structure**
```typescript
{
"name": string
"description"?: string // Optional
"chatbotFileId"?: string (uuid) // Optional
"knowledgeBaseFileId"?: string (uuid) // Optional
"numTestCases"?: integer // Optional
}
```
**Example Request Values**
```json
{
"name": "Example name",
"description": "Example string",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/dataset/generate-from-file/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example name",
"description": "Example string",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"name": "Example name",
"description": "Example string",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
};
axios.post("https://api.maiagent.ai/api/v1/dataset/generate-from-file/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/generate-from-file/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"name": "Example name",
"description": "Example string",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/dataset/generate-from-file/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => 'Example name',
'description' => 'Example string',
'chatbotFileId' => '550e8400-e29b-41d4-a716-446655440000',
'knowledgeBaseFileId' => '550e8400-e29b-41d4-a716-446655440000',
'numTestCases' => 123
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 202**
**Example Response Structure**
```typescript
{
"status": string (enum: accepted) // * `accepted` - Always accepted, indicating the request has been accepted and queued for background execution
"message": string // Acceptance message
"taskId": string // Background task ID
}
```
**Example Response Values**
```json
{
"status": "accepted",
"message": "Response string",
"taskId": "Response string"
}
```
***
### List knowledge base files available for test case generation
GET `/api/v1/dataset/knowledge-base-files/`
{% hint style="info" %}
Grouped by knowledge base, lists only fully processed files of type txt, docx, pdf, md, markdown, or mdx. `pageSize` is the maximum number of files returned per knowledge base (default 5, maximum 100); `search` filters by filename.
{% endhint %}
#### Parameters
| Parameter name | Required | Type | Description |
| -------------- | -------- | ------- | ---------------------------------------------------------------------------- |
| `pageSize` | ❌ | integer | Maximum number of files returned per knowledge base (default 5, maximum 100) |
| `search` | ❌ | string | Filter by filename (case-insensitive partial match) |
#### Code examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response body
**Status code: 200**
**Example response schema**
```typescript
{
"knowledgeBases": [ // Knowledge bases with available files, sorted by name; knowledge bases without available files are excluded
{
"id": string (uuid)
"name": string
"files":
{
"count": integer // Total number of matching files in this knowledge base
"results": [ // The latest page_size files
{
"id": string (uuid)
"filename": string
"fileType": string
"size": integer // File size in bytes
"knowledgeBase":
{
"id": string (uuid)
"name": string
}
}
]
}
}
]
}
```
**Example response values**
```json
{
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"files": {
"count": 456,
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "Response string",
"fileType": "Response string",
"size": 456,
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
}
}
]
}
}
]
}
```
***
### Retrieve a specific test set
GET `/api/v1/dataset/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ----------- |
| `id` | ✅ | string | Dataset ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // Optional
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // Optional
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Retrieve a test set with its single-turn test cases
GET `/api/v1/dataset/{id}/details/`
{% hint style="info" %}
In addition to the test set fields, the response includes a `testCases` array that contains only single-turn test cases; for multi-turn test cases, use `GET /api/v1/multi-turn-test-case/?datasetId={id}`.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ----------- |
| `id` | ✅ | string | Dataset ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // Optional
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // Optional
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"testCases": [ // All single-turn test cases in this test set, ordered from oldest to newest by creation time; an empty array when there are no test cases
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // Optional
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (Optional)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (Optional)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "Response string",
"updatedAt": "Response string",
"testCases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"question": "Response string",
"groundTruth": "Response string",
"status": "active",
"creationMethod": "manual",
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
]
}
```
***
### Update a test set
PUT `/api/v1/dataset/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ----------- |
| `id` | ✅ | string | Dataset ID |
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| ----------- | ------- | -------- | ----------- |
| name | string | Yes | |
| description | string | No | |
| isActive | boolean | No | |
**Example Request Structure**
```typescript
{
"name": string
"description"?: string // Optional
"isActive"?: boolean // Optional
}
```
**Example Request Values**
```json
{
"name": "Example name",
"description": "Example string",
"isActive": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example name",
"description": "Example string",
"isActive": true
}'
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"name": "Example name",
"description": "Example string",
"isActive": true
};
axios.put("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"name": "Example name",
"description": "Example string",
"isActive": True
}
response = requests.put(url, json=data, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => 'Example name',
'description' => 'Example string',
'isActive' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status Code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // Optional
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // Optional
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Partially update a test set
PATCH `/api/v1/dataset/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ----------- |
| `id` | ✅ | string | Dataset ID |
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| ----------- | ------- | -------- | ----------- |
| name | string | No | |
| description | string | No | |
| isActive | boolean | No | |
**Example Request Structure**
```typescript
{
"name"?: string // Optional
"description"?: string // Optional
"isActive"?: boolean // Optional
}
```
**Example Request Values**
```json
{
"name": "Example name",
"description": "Example string",
"isActive": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example name",
"description": "Example string",
"isActive": true
}'
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"name": "Example name",
"description": "Example string",
"isActive": true
};
axios.patch("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"name": "Example name",
"description": "Example string",
"isActive": True
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => 'Example name',
'description' => 'Example string',
'isActive' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status Code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // Optional
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // Optional
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Delete a test set
DELETE `/api/v1/dataset/{id}/`
{% hint style="info" %}
This cannot be undone. Deleting a test set also deletes all test cases in it, as well as the evaluations and results that were run with this test set.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ----------- |
| `id` | ✅ | string | Dataset ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request payload
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
| Status code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
### List single-turn test cases
GET `/api/v1/test-case/`
{% hint style="info" %}
Use `datasetId` to filter by a single test set. You can also filter by `status` and `creationMethod` (`manual`, `file`, `generate`).
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| ---------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `creationMethod` | ❌ | string | List only test cases created with this method. Allowed values: \`manual\`: Manual ; \`file\`: File import ; \`generate\`: Generated; |
| `datasetId` | ❌ | string | List only test cases from this dataset |
| `ordering` | ❌ | string | Sort field: created\_at or updated\_at. Prefix with - for newest first (e.g. -updated\_at). If not specified, sorted by creation time, newest first |
| `page` | ❌ | integer | Page number, starting from 1. Returns 404 if beyond the last page |
| `pageSize` | ❌ | integer | Number of items per page. Default 20, maximum 100 (values above 100 are treated as 100) |
| `query` | ❌ | string | Keyword matched against the question, ground truth, or ID (partial match) |
| `search` | ❌ | string | Keyword matched against the question or ground truth (partial match, case-insensitive; when multiple keywords are separated by spaces, all must match) |
| `status` | ❌ | string | List only test cases with this status. Allowed values: \`active\`: Active ; \`inactive\`: Inactive ; \`pending\`: Pending Review; |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active", config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status Code: 200**
**Example Response Structure**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // Optional
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (Optional)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (Optional)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**Example Response Values**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"question": "Response string",
"groundTruth": "Response string",
"status": "active",
"creationMethod": "manual",
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
]
}
```
***
### Create a Single-Turn Test Case
POST `/api/v1/test-case/`
{% hint style="info" %}
`datasetId`, `question`, and `groundTruth` are required. `status` defaults to `active`; evaluations only run test cases that are `active`.
{% endhint %}
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| ----------- | ------------- | -------- | ----------- |
| datasetId | string (uuid) | Yes | |
| question | string | Yes | |
| groundTruth | string | Yes | |
| status | string | No | |
| flaky | boolean | No | |
**Example Request Structure**
```typescript
{
"datasetId": string (uuid)
"question": string
"groundTruth": string
"status"?: string // Optional
"flaky"?: boolean // Optional
}
```
**Example Request Values**
```json
{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"question": "Example string",
"groundTruth": "Example string",
"status": "Example string",
"flaky": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"question": "Example string",
"groundTruth": "Example string",
"status": "Example string",
"flaky": true
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"question": "Example string",
"groundTruth": "Example string",
"status": "Example string",
"flaky": true
};
axios.post("https://api.maiagent.ai/api/v1/test-case/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"question": "Example string",
"groundTruth": "Example string",
"status": "Example string",
"flaky": True
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/test-case/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
'question' => 'Example string',
'groundTruth' => 'Example string',
'status' => 'Example string',
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 201**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // Optional
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (Optional)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (Optional)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"question": "Response string",
"groundTruth": "Response string",
"status": "active",
"creationMethod": "manual",
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Upload a CSV or Excel File to Add Test Cases
POST `/api/v1/test-case/upload/`
{% hint style="info" %}
Upload with `multipart/form-data`; both `file` and `dataset_id` are required. The file must be `.csv`, `.xlsx`, or `.xls`, and the header row must include the `question` and `ground_truth` columns. Each row adds one single-turn test case. Use UTF-8 encoding for CSV files. The response is an array of the newly created test cases.
{% endhint %}
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/upload/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-F "file=@example_file.csv" \
-F "dataset_id=550e8400-e29b-41d4-a716-446655440000"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
const FormData = require('form-data');
// Create a FormData object
const formData = new FormData();
// Replace with the actual file
formData.append('file', /* actual file object */, 'example_file.csv');
formData.append('dataset_id', '550e8400-e29b-41d4-a716-446655440000');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
...formData.getHeaders()
}
};
axios.post("https://api.maiagent.ai/api/v1/test-case/upload/", formData, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred with the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/upload/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
# Create the file and form data
files = {
'file': ('example_file.csv', open('example_file.csv', 'rb'), 'text/csv'),
'dataset_id': (None, '550e8400-e29b-41d4-a716-446655440000')
}
response = requests.post(url, files=files, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("An error occurred with the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/test-case/upload/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
],
'multipart' => [
[
'name' => 'file',
'contents' => fopen('example_file.csv', 'r'),
'filename' => 'example_file.csv'
],
[
'name' => 'dataset_id',
'contents' => '550e8400-e29b-41d4-a716-446655440000'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred with the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status code: 201**
**Example Response Structure**
```typescript
[
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // Optional
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (Optional)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (Optional)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
```
**Example Response Values**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"question": "Response string",
"groundTruth": "Response string",
"status": "active",
"creationMethod": "manual",
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
]
```
***
### Generate Single-Turn Test Cases from Knowledge Base Files
POST `/api/v1/test-case/generate-from-file/`
{% hint style="info" %}
Specify the source with `knowledgeBaseIds` (expanded to all processed files of a supported type in the knowledge base) or `knowledgeBaseFileIds`; the two can be used together. Supported formats are txt, docx, pdf, md, markdown, and mdx. `numTestCases` is the total number of test cases to generate in this run (default 10). If the number of files or test cases exceeds the platform limit, the API returns `400` and the message states the limit. Generation runs in the background, and the response is `202` with a `jobId`. If the same dataset already has a generation job in progress, that job's `jobId` is returned and no duplicate job is created. **Credit**: The organization's Credit is checked before submission, and `402` is returned if it is insufficient; `agentops_test_gen` is deducted based on the number of test cases actually generated.
{% endhint %}
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| -------------------- | -------------- | -------- | ---------------------------------------------------------------------- |
| chatbotFileIds | array\[string] | No | List of KnowledgeBaseFile IDs to generate test cases from (deprecated) |
| knowledgeBaseFileIds | array\[string] | No | List of KnowledgeBaseFile IDs to generate test cases from |
| knowledgeBaseIds | array\[string] | No | List of KnowledgeBase IDs to generate test cases from all their files |
| datasetId | string (uuid) | Yes | |
| numTestCases | integer | No | |
**Example Request Structure**
```typescript
{
"chatbotFileIds"?: [ // List of KnowledgeBaseFile IDs to generate test cases from (deprecated) (Optional)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // List of KnowledgeBaseFile IDs to generate test cases from (Optional)
string (uuid)
]
"knowledgeBaseIds"?: [ // List of KnowledgeBase IDs to generate test cases from all their files (Optional)
string (uuid)
]
"datasetId": string (uuid)
"numTestCases"?: integer // Optional
}
```
**Example Request Values**
```json
{
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/generate-from-file/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}'
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
};
axios.post("https://api.maiagent.ai/api/v1/test-case/generate-from-file/", data, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred with the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/generate-from-file/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}
response = requests.post(url, json=data, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("An error occurred with the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/test-case/generate-from-file/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'chatbotFileIds' => [
'550e8400-e29b-41d4-a716-446655440000'
],
'knowledgeBaseFileIds' => [
'550e8400-e29b-41d4-a716-446655440000'
],
'knowledgeBaseIds' => [
'550e8400-e29b-41d4-a716-446655440000'
],
'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
'numTestCases' => 123
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred with the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status code: 202**
**Example Response Structure**
```typescript
{
"status": string (enum: accepted) // * `accepted` - Always accepted, indicating the request was accepted and queued for background execution
"message": string // Acceptance message
"jobId": string (uuid) // Generation job ID. Use GET /api/v1/test-case/generation-jobs/{jobId}/ to check progress. If the same dataset already has a generation job in progress, the ID of that job is returned
"taskId": string // Background task ID
}
```
**Example Response Values**
```json
{
"status": "accepted",
"message": "Response string",
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"taskId": "Response string"
}
```
***
### List Test Case Generation Jobs
GET `/api/v1/test-case/generation-jobs/`
{% hint style="info" %}
Lists the organization's single-turn and multi-turn generation jobs, sorted from newest to oldest. Filter by `datasetId` and `status`.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------- | --------------------------------------------------------------------------------------- |
| `datasetId` | ❌ | string | List only generation jobs for this dataset |
| `page` | ❌ | integer | Page number, starting from 1. Returns 404 if beyond the last page |
| `pageSize` | ❌ | integer | Number of items per page. Default 20, maximum 100 (values above 100 are treated as 100) |
| `status` | ❌ | string | Filter by status: pending / running / completed / partial\_completed / failed |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/test-case/generation-jobs/?datasetId=example&page=1&pageSize=1&status=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/?datasetId=example&page=1&pageSize=1&status=example", config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred with the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/generation-jobs/?datasetId=example&page=1&pageSize=1&status=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("An error occurred with the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/?datasetId=example&page=1&pageSize=1&status=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred with the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status code: 200**
**Example Response Structure**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"status"?: string (enum: pending, running, completed, partial_completed, failed) // * `pending` - Pending
* `running` - Generating
* `completed` - Completed
* `partial_completed` - Partially completed
* `failed` - Generation failed (Optional)
"jobType"?: // Single-turn Q&A test data or multi-turn conversation test data
* `single_turn` - Single turn
* `multi_turn` - Multi turn (Optional)
{
}
"requestedNumTestCases"?: integer // Optional
"totalFiles"?: integer // Optional
"processedFiles"?: integer // Optional
"generatedCount"?: integer // Optional
"progressPercentage": number (double)
"errorMessage"?: string // Error message recorded when the whole batch fails (Optional)
"fileResults"?: object // Result for each file, such as [{'file_id', 'filename', 'status', 'generated', 'error'}] (Optional)
"startedAt"?: string (timestamp) // Optional
"completedAt"?: string (timestamp) // Optional
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**Example Response Values**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"status": "pending",
"jobType": {},
"requestedNumTestCases": 456,
"totalFiles": 456,
"processedFiles": 456,
"generatedCount": 456,
"progressPercentage": 456,
"errorMessage": "Response string",
"fileResults": null,
"startedAt": "Response string",
"completedAt": "Response string",
"createdAt": "Response string",
"updatedAt": "Response string"
}
]
}
```
***
### Get Test Case Generation Job Progress
GET `/api/v1/test-case/generation-jobs/{jobId}/`
{% hint style="info" %}
`status` is `pending`, `running`, `completed`, `partial_completed`, or `failed`. `generatedCount` is the number of test cases generated so far, and `fileResults` lists the result and failure reason for each file. Both single-turn and multi-turn generation jobs are queried through this endpoint and are distinguished by `jobType`.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | --------------------------------------------------------------------------------------------- |
| `jobId` | ✅ | string | Generation job ID, i.e. the jobId returned by "Generate Test Cases from Knowledge Base Files" |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/test-case/generation-jobs/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred with the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/generation-jobs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("An error occurred with the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred with the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"status"?: string (enum: pending, running, completed, partial_completed, failed) // * `pending` - Pending
* `running` - Generating
* `completed` - Completed
* `partial_completed` - Partially completed
* `failed` - Generation failed (Optional)
"jobType"?: // Single-turn Q&A test data or multi-turn conversation test data
* `single_turn` - Single turn
* `multi_turn` - Multi turn (Optional)
{
}
"requestedNumTestCases"?: integer // Optional
"totalFiles"?: integer // Optional
"processedFiles"?: integer // Optional
"generatedCount"?: integer // Optional
"progressPercentage": number (double)
"errorMessage"?: string // Error message recorded when the whole batch fails (Optional)
"fileResults"?: object // Result for each file, such as [{'file_id', 'filename', 'status', 'generated', 'error'}] (Optional)
"startedAt"?: string (timestamp) // Optional
"completedAt"?: string (timestamp) // Optional
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"status": "pending",
"jobType": {},
"requestedNumTestCases": 456,
"totalFiles": 456,
"processedFiles": 456,
"generatedCount": 456,
"progressPercentage": 456,
"errorMessage": "Response string",
"fileResults": null,
"startedAt": "Response string",
"completedAt": "Response string",
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Update a Single-Turn Test Case
PUT `/api/v1/test-case/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------ |
| `id` | ✅ | string | Test case ID |
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| ----------- | ---------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| question | string | Yes | |
| groundTruth | string | No | |
| status | string (enum: active, inactive, pending) | No | `active`: Active ; `inactive`: Inactive ; `pending`: Pending Review; |
| flaky | boolean | No | Flaky test cases still run and keep their results, but are excluded from the pass rate. |
**Example Request Structure**
```typescript
{
"question": string
"groundTruth"?: string // Optional
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
}
```
**Example Request Values**
```json
{
"question": "Example string",
"groundTruth": "Example string",
"status": "active",
"flaky": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Example string",
"groundTruth": "Example string",
"status": "active",
"flaky": true
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request body (payload)
const data = {
"question": "Example string",
"groundTruth": "Example string",
"status": "active",
"flaky": true
};
axios.put("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"question": "Example string",
"groundTruth": "Example string",
"status": "active",
"flaky": True
}
response = requests.put(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'question' => 'Example string',
'groundTruth' => 'Example string',
'status' => 'active',
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // Optional
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (Optional)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (Optional)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"question": "Response string",
"groundTruth": "Response string",
"status": "active",
"creationMethod": "manual",
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Partially Update Single-Turn Test Case
PATCH `/api/v1/test-case/{id}/`
{% hint style="info" %}
To temporarily skip a question, set `status` to `inactive`. Evaluations will skip it, and past evaluation results are kept.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------ |
| `id` | ✅ | string | Test case ID |
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| ----------- | ---------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| question | string | No | |
| groundTruth | string | No | |
| status | string (enum: active, inactive, pending) | No | `active`: Active ; `inactive`: Inactive ; `pending`: Pending Review; |
| flaky | boolean | No | Flaky test cases still run and keep their results, but are excluded from the pass rate. |
**Example Request Structure**
```typescript
{
"question"?: string // Optional
"groundTruth"?: string // Optional
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
}
```
**Example Request Values**
```json
{
"question": "Example string",
"groundTruth": "Example string",
"status": "active",
"flaky": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Example string",
"groundTruth": "Example string",
"status": "active",
"flaky": true
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request body (payload)
const data = {
"question": "Example string",
"groundTruth": "Example string",
"status": "active",
"flaky": true
};
axios.patch("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"question": "Example string",
"groundTruth": "Example string",
"status": "active",
"flaky": True
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'question' => 'Example string',
'groundTruth' => 'Example string',
'status' => 'active',
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // Optional
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (Optional)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (Optional)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"question": "Response string",
"groundTruth": "Response string",
"status": "active",
"creationMethod": "manual",
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Delete Single-Turn Test Case
DELETE `/api/v1/test-case/{id}/`
{% hint style="info" %}
This also deletes this test case's per-question results from past evaluations. To only pause testing, use `status` instead.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------ |
| `id` | ✅ | string | Test case ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request body (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response
| Status code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
### Bulk delete single-turn test cases
POST `/api/v1/test-case/bulk-delete/`
{% hint style="info" %}
Pass an array of test case IDs to delete as `testCaseIds`; success returns `204`. The impact of deletion is the same as [Delete a single-turn test case](#test-case-destroy).
{% endhint %}
#### Request
**Request Parameters**
| Field | Type | Required | Description |
| --------------- | -------------- | -------- | ------------------------------- |
| test\_case\_ids | array\[string] | Yes | List of test case IDs to delete |
**Request Schema Example**
```typescript
{
"test_case_ids": [ // List of test case IDs to delete
string (uuid)
]
}
```
**Request Example Values**
```json
{
"test_case_ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/bulk-delete/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"test_case_ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request body (payload)
const data = {
"test_case_ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/test-case/bulk-delete/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/bulk-delete/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"test_case_ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/test-case/bulk-delete/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'test_case_ids' => [
'550e8400-e29b-41d4-a716-446655440000'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response
| Status code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
### List Multi-Turn Test Cases
GET `/api/v1/multi-turn-test-case/`
{% hint style="info" %}
Use `datasetId` to filter by a single test set.
{% endhint %}
#### Parameters
| Parameter | Required | Type | Description |
| ----------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dataset` | ❌ | string | Same as datasetId. Lists only the multi-turn conversation test cases of this dataset |
| `datasetId` | ❌ | string | Lists only the multi-turn conversation test cases of this dataset |
| `ordering` | ❌ | string | Sort field: created\_at or updated\_at. Prefix with - for newest first (e.g. -updated\_at). If not specified, results are sorted by creation time, newest first |
| `page` | ❌ | integer | Page number, starting from 1. Returns 404 if beyond the last page |
| `pageSize` | ❌ | integer | Number of items per page. Default 20, maximum 100 (values above 100 are treated as 100) |
| `search` | ❌ | string | Keyword. Matches the scenario or the expected outcome (expected\_outcome) (partial match, case-insensitive; when multiple keywords are separated by spaces, all of them must match) |
| `status` | ❌ | string | Lists only multi-turn conversation test cases with this status. Allowed values: \`active\`: Active ; \`inactive\`: Inactive; |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active", config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred during the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (Optional)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (Optional)
"creationMethod":
{
}
"sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**Example Response Values**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"scenario": "Response string",
"expectedOutcome": "Response string",
"userDescription": "Response string",
"status": "active",
"creationMethod": {},
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
]
}
```
***
### Create a multi-turn test case
POST `/api/v1/multi-turn-test-case/`
{% hint style="info" %}
`datasetId`, `scenario` (the task scenario the simulated user should accomplish), and `expectedOutcome` (the outcome a successful conversation should reach, which is also the stop condition for the simulated conversation) are required; `userDescription` is optional and describes the simulated user's tone, background, and level of expertise.
{% endhint %}
#### Request
**Request Parameters**
| Field | Type | Required | Description |
| --------------- | ------------- | -------- | ----------- |
| datasetId | string (uuid) | Yes | |
| scenario | string | Yes | |
| expectedOutcome | string | Yes | |
| userDescription | string | No | |
| status | object | No | |
| flaky | boolean | No | |
**Request Schema Example**
```typescript
{
"datasetId": string (uuid)
"scenario": string
"expectedOutcome": string
"userDescription"?: string // Optional
"status"?: // Optional
{
}
"flaky"?: boolean // Optional
}
```
**Request Example Values**
```json
{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": {},
"flaky": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/multi-turn-test-case/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": {},
"flaky": true
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request body (payload)
const data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": {},
"flaky": true
};
axios.post("https://api.maiagent.ai/api/v1/multi-turn-test-case/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": {},
"flaky": True
}
response = requests.post(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/multi-turn-test-case/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
'scenario' => 'Example string',
'expectedOutcome' => 'Example string',
'userDescription' => 'Example string',
'status' => new \stdClass(),
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response
**Status code: 201**
**Response Schema Example**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (Optional)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (Optional)
"creationMethod":
{
}
"sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Response Example Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"scenario": "Response string",
"expectedOutcome": "Response string",
"userDescription": "Response string",
"status": "active",
"creationMethod": {},
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Generate Multi-Turn Test Cases from Knowledge Base Files
POST `/api/v1/multi-turn-test-case/generate-from-file/`
{% hint style="info" %}
Specify the source files with `knowledgeBaseFileIds`; `numTestCases` defaults to 5 and allows at most 20. Generation runs in the background and returns `202` with a `jobId`; track it with [Retrieve test case generation job progress](#test-case-generation-jobs-retrieve). **Credit**: Same as single-turn generation; `agentops_test_gen` is deducted based on the number of questions actually generated.
{% endhint %}
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| -------------------- | -------------- | -------- | -------------------------------------------------------------------- |
| datasetId | string (uuid) | Yes | |
| knowledgeBaseFileIds | array\[string] | Yes | List of KnowledgeBaseFile IDs to generate multi-turn test cases from |
| numTestCases | integer | No | |
**Example Request Structure**
```typescript
{
"datasetId": string (uuid)
"knowledgeBaseFileIds": [ // List of KnowledgeBaseFile IDs to generate multi-turn test cases from
string (uuid)
]
"numTestCases"?: integer // Optional
}
```
**Example Request Values**
```json
{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"numTestCases": 123
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"numTestCases": 123
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"numTestCases": 123
};
axios.post("https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/", data, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred during the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"numTestCases": 123
}
response = requests.post(url, json=data, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
'knowledgeBaseFileIds' => [
'550e8400-e29b-41d4-a716-446655440000'
],
'numTestCases' => 123
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status Code: 202**
**Example Response Structure**
```typescript
{
"status": string (enum: accepted) // * `accepted` - Always accepted, indicating the request has been accepted and queued for background execution
"message": string // Acceptance message
"jobId": string (uuid) // Generation job ID; use GET /api/v1/test-case/generation-jobs/{jobId}/ to check progress. If the same test set already has a generation job in progress, that job is returned
"taskId": string // Background task ID
}
```
**Example Response Values**
```json
{
"status": "accepted",
"message": "Response string",
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"taskId": "Response string"
}
```
***
### Retrieve a Specific Multi-Turn Test Case
GET `/api/v1/multi-turn-test-case/{id}/`
#### Parameters
| Parameter | Required | Type | Description |
| --------- | -------- | ------ | ----------------------- |
| `id` | ✅ | string | Multi-turn test case ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred during the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status Code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (Optional)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (Optional)
"creationMethod":
{
}
"sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"scenario": "Response string",
"expectedOutcome": "Response string",
"userDescription": "Response string",
"status": "active",
"creationMethod": {},
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Update a Multi-Turn Test Case
PUT `/api/v1/multi-turn-test-case/{id}/`
#### Parameters
| Parameter | Required | Type | Description |
| --------- | -------- | ------ | ----------------------- |
| `id` | ✅ | string | Multi-turn test case ID |
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| --------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| scenario | string | Yes | Task scenario the simulated user should accomplish |
| expectedOutcome | string | Yes | Outcome a successful conversation should reach, also used as the simulation stop condition |
| userDescription | string | No | Persona of the simulated user, such as tone, background and level of expertise |
| status | string (enum: active, inactive) | No | `active`: Active ; `inactive`: Inactive; |
| flaky | boolean | No | Flaky test cases still run and keep their results, but are excluded from the pass rate. |
**Example Request Structure**
```typescript
{
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (Optional)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
}
```
**Example Request Values**
```json
{
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": "active",
"flaky": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": "active",
"flaky": true
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": "active",
"flaky": true
};
axios.put("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred during the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": "active",
"flaky": True
}
response = requests.put(url, json=data, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'scenario' => 'Example string',
'expectedOutcome' => 'Example string',
'userDescription' => 'Example string',
'status' => 'active',
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status Code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (Optional)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (Optional)
"creationMethod":
{
}
"sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"scenario": "Response string",
"expectedOutcome": "Response string",
"userDescription": "Response string",
"status": "active",
"creationMethod": {},
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Partially Update a Multi-Turn Test Case
PATCH `/api/v1/multi-turn-test-case/{id}/`
#### Parameters
| Parameter | Required | Type | Description |
| --------- | -------- | ------ | ----------------------- |
| `id` | ✅ | string | Multi-turn test case ID |
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| --------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| scenario | string | No | Task scenario the simulated user should accomplish |
| expectedOutcome | string | No | Outcome a successful conversation should reach, also used as the simulation stop condition |
| userDescription | string | No | Persona of the simulated user, such as tone, background and level of expertise |
| status | string (enum: active, inactive) | No | `active`: Active ; `inactive`: Inactive; |
| flaky | boolean | No | Flaky test cases still run and keep their results, but are excluded from the pass rate. |
**Example Request Structure**
```typescript
{
"scenario"?: string // Task scenario the simulated user should accomplish (Optional)
"expectedOutcome"?: string // Outcome a successful conversation should reach, also used as the simulation stop condition (Optional)
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (Optional)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
}
```
**Example Request Values**
```json
{
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": "active",
"flaky": true
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": "active",
"flaky": true
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request payload
const data = {
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": "active",
"flaky": true
};
axios.patch("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('An error occurred during the request:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request payload
data = {
"scenario": "Example string",
"expectedOutcome": "Example string",
"userDescription": "Example string",
"status": "active",
"flaky": True
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("An error occurred during the request:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'scenario' => 'Example string',
'expectedOutcome' => 'Example string',
'userDescription' => 'Example string',
'status' => 'active',
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status Code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (Optional)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (Optional)
"creationMethod":
{
}
"sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"scenario": "Response string",
"expectedOutcome": "Response string",
"userDescription": "Response string",
"status": "active",
"creationMethod": {},
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
}
```
***
### Delete a Multi-Turn Test Case
DELETE `/api/v1/multi-turn-test-case/{id}/`
#### Parameters
| Parameter | Required | Type | Description |
| --------- | -------- | ------ | ----------------------- |
| `id` | ✅ | string | Multi-turn test case ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request body (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
| Status Code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
### List Available Evaluation Models
GET `/api/v1/evaluations/evaluation-llms/`
{% hint style="info" %}
The model whose `isDefault` is `true` is the default evaluation model used when `evaluationLlmId` is not specified for an evaluation run.
{% endhint %}
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/", config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 200**
**Response Schema Example**
```typescript
[
{
"id": string (uuid)
"name": string
"value": string
"provider": string
"isDefault": boolean
}
]
```
**Example Response Values**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"value": "Response string",
"provider": "Response string",
"isDefault": false
}
]
```
***
### Run Single-Turn Evaluation
POST `/api/v1/evaluations/evaluate/`
{% hint style="info" %}
`datasetId` and `chatbotId` are required; if `evaluationLlmId` is omitted, the default evaluation model is used. `metricConfig` turns built-in metrics on or off with boolean values, and `customMetrics` accepts up to 10 custom metrics. Only test cases with the `active` status are evaluated. The evaluation runs in the background and the response is `202` with an `evaluationId`. **Credit**: The organization's Credit is checked before submission, and `402` is returned if it is insufficient; when the evaluation finishes, `agentops_test_run` and `agentops_deepeval` are deducted based on the number of completed test cases, and calls to the evaluation model are charged separately.
{% endhint %}
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| --------------- | ------------------------------------- | -------- | ----------- |
| datasetId | string (uuid) | Yes | |
| chatbotId | string (uuid) | Yes | |
| evaluationLlmId | string (uuid) | No | |
| name | string | No | |
| description | string | No | |
| metricConfig | object | No | |
| customMetrics | array\[DatasetEvaluationCustomMetric] | No | |
**Example Request Structure**
```typescript
{
"datasetId": string (uuid)
"chatbotId": string (uuid)
"evaluationLlmId"?: string (uuid) // Optional
"name"?: string // Optional
"description"?: string // Optional
"metricConfig"?: object // Optional
"customMetrics"?: [ // Optional
{
"name": string
"criteria"?: string // Optional
"evaluationSteps"?: [ // Optional
string
]
"threshold"?: number (double) // Optional
}
]
}
```
**Example Request Values**
```json
{
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Evaluation Name",
"description": "Evaluation Description",
"metric_config": {
"ground_truth": true,
"task_completion": false,
"tool_correctness": false,
"guardrail": true,
"summarize": false,
"hallucination": true
},
"custom_metrics": [
{
"name": "Support Tone",
"criteria": "The answer should be polite, empathetic, and professional in tone.",
"threshold": 0.6
}
]
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/evaluate/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Evaluation Name",
"description": "Evaluation Description",
"metric_config": {
"ground_truth": true,
"task_completion": false,
"tool_correctness": false,
"guardrail": true,
"summarize": false,
"hallucination": true
},
"custom_metrics": [
{
"name": "Support Tone",
"criteria": "The answer should be polite, empathetic, and professional in tone.",
"threshold": 0.6
}
]
}'
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request body (payload)
const data = {
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Evaluation Name",
"description": "Evaluation Description",
"metric_config": {
"ground_truth": true,
"task_completion": false,
"tool_correctness": false,
"guardrail": true,
"summarize": false,
"hallucination": true
},
"custom_metrics": [
{
"name": "Support Tone",
"criteria": "The answer should be polite, empathetic, and professional in tone.",
"threshold": 0.6
}
]
};
axios.post("https://api.maiagent.ai/api/v1/evaluations/evaluate/", data, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/evaluate/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Evaluation Name",
"description": "Evaluation Description",
"metric_config": {
"ground_truth": True,
"task_completion": False,
"tool_correctness": False,
"guardrail": True,
"summarize": False,
"hallucination": True
},
"custom_metrics": [
{
"name": "Support Tone",
"criteria": "The answer should be polite, empathetic, and professional in tone.",
"threshold": 0.6
}
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/evaluations/evaluate/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'dataset_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'chatbot_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'evaluation_llm_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'name' => 'Evaluation Name',
'description' => 'Evaluation Description',
'metric_config' => [
'ground_truth' => true,
'task_completion' => false,
'tool_correctness' => false,
'guardrail' => true,
'summarize' => false,
'hallucination' => true
],
'custom_metrics' => [
[
'name' => 'Support Tone',
'criteria' => 'The answer should be polite, empathetic, and professional in tone.',
'threshold' => 0.6
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 202**
**Response Schema Example**
```typescript
{
"status": string (enum: accepted) // * `accepted` - Always accepted, indicating the request has been accepted and queued for background execution
"message": string // Acceptance message
"evaluationId": string (uuid) // Evaluation ID; poll status with GET /api/v1/evaluations/{id}/ until it finishes
}
```
**Example Response Values**
```json
{
"status": "accepted",
"message": "Response string",
"evaluationId": "550e8400-e29b-41d4-a716-446655440000"
}
```
***
### Run Multi-Turn Evaluation
POST `/api/v1/evaluations/multi-turn-evaluate/`
{% hint style="info" %}
Simulates a conversation between a user and the Agent using the multi-turn test cases in the test set, then scores it. `maxTurns` is the maximum number of turns the simulated user speaks (2–10, default 6), and `language` is the language of the simulated user (`Traditional Chinese`, `Simplified Chinese`, `English`, `Japanese`, `Korean`; default `Traditional Chinese`). Returns `400` if the test set has no `active` multi-turn test cases. The response and Credit handling are the same as [Run a single-turn evaluation](#evaluations-evaluate-create).
{% endhint %}
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| ------------------------ | ----------------------------- | -------- | ----------- |
| datasetId | string (uuid) | Yes | |
| chatbotId | string (uuid) | Yes | |
| evaluationLlmId | string (uuid) | No | |
| name | string | No | |
| description | string | No | |
| maxTurns | integer | No | |
| minTurns | integer | No | |
| turnFaithfulness | boolean | No | |
| turnRelevancy | boolean | No | |
| conversationCompleteness | boolean | No | |
| language | object | No | |
| customMetrics | array\[MultiTurnCustomMetric] | No | |
**Example Request Structure**
```typescript
{
"datasetId": string (uuid)
"chatbotId": string (uuid)
"evaluationLlmId"?: string (uuid) // Optional
"name"?: string // Optional
"description"?: string // Optional
"maxTurns"?: integer // Optional
"minTurns"?: integer // Optional
"turnFaithfulness"?: boolean // Optional
"turnRelevancy"?: boolean // Optional
"conversationCompleteness"?: boolean // Optional
"language"?: // Optional
{
}
"customMetrics"?: [ // Optional
{
"name": string
"criteria"?: string // Optional
"evaluationSteps"?: [ // Optional
string
]
"threshold"?: number (double) // Optional
}
]
}
```
**Example Request Values**
```json
{
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"max_turns": 6,
"min_turns": 2,
"custom_metrics": [
{
"name": "Identity Check",
"criteria": "The assistant confirms the user identity before sharing account details.",
"threshold": 0.6
}
]
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"max_turns": 6,
"min_turns": 2,
"custom_metrics": [
{
"name": "Identity Check",
"criteria": "The assistant confirms the user identity before sharing account details.",
"threshold": 0.6
}
]
}'
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request body (payload)
const data = {
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"max_turns": 6,
"min_turns": 2,
"custom_metrics": [
{
"name": "Identity Check",
"criteria": "The assistant confirms the user identity before sharing account details.",
"threshold": 0.6
}
]
};
axios.post("https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/", data, config)
.then(response => {
console.log('Successfully retrieved the response:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"max_turns": 6,
"min_turns": 2,
"custom_metrics": [
{
"name": "Identity Check",
"criteria": "The assistant confirms the user identity before sharing account details.",
"threshold": 0.6
}
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("Successfully retrieved the response:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'dataset_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'chatbot_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'max_turns' => 6,
'min_turns' => 2,
'custom_metrics' => [
[
'name' => 'Identity Check',
'criteria' => 'The assistant confirms the user identity before sharing account details.',
'threshold' => 0.6
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "Successfully retrieved the response:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status Code: 202**
**Response Schema Example**
```typescript
{
"status": string (enum: accepted) // * `accepted` - Always accepted, indicating the request has been accepted and queued for background execution
"message": string // Acceptance message
"evaluationId": string (uuid) // Evaluation ID; poll status with GET /api/v1/evaluations/{id}/ until it finishes
}
```
**Example Response Values**
```json
{
"status": "accepted",
"message": "Response string",
"evaluationId": "550e8400-e29b-41d4-a716-446655440000"
}
```
***
### List Evaluations
GET `/api/v1/evaluations/`
{% hint style="info" %}
Filter by `datasetId`, `chatbotId`, and `status`.
{% endhint %}
#### Parameters
| Parameter | Required | Type | Description |
| ---------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chatbotId` | ❌ | string | List only evaluations of this AI assistant |
| `datasetId` | ❌ | string | List only evaluations that use this dataset |
| `excludeBuiltIn` | ❌ | string | When true, exclude data from official built-in Agents (locked instances created by renting from the Agent Marketplace), leaving only assistants created by the organization. Copies made with “Copy as Custom” count as custom assistants. Omitting this parameter or setting it to false applies no such filter. |
| `ordering` | ❌ | string | Sort by created\_at or updated\_at. Prefix with - for newest first (e.g., -updated\_at). Defaults to creation time, newest first |
| `page` | ❌ | integer | Page number, starting at 1; returns 404 if the number exceeds the last page |
| `pageSize` | ❌ | integer | Results per page; defaults to 20, with a maximum of 100 (values above 100 are capped at 100) |
| `query` | ❌ | string | Keyword matched against the evaluation name, description, or ID (partial match) |
| `search` | ❌ | string | Keyword matched against the evaluation name, dataset name, or AI assistant name (case-insensitive partial match; all space-separated keywords must match) |
| `status` | ❌ | string | List only evaluations with this status. Allowed values: \`pending\`: Pending evaluation ; \`running\`: Evaluating ; \`stopping\`: Stopping ; \`completed\`: Completed ; \`partial\_completed\`: Partially completed ; \`failed\`: Evaluation failed; |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&excludeBuiltIn=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&excludeBuiltIn=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&excludeBuiltIn=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&excludeBuiltIn=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Body
**Status code: 200**
**Example Response Schema**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"name": string
"description": string
"chatbot":
{
"id": string (uuid)
"name": string
}
"dataset":
{
"id": string (uuid)
"name": string
}
"organization":
{
"id": string (uuid)
"name": string
}
"evaluationLlm":
{
"id": string (uuid)
"name": string
}
"status":
{
}
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"totalTestCases": integer
"completedTestCases": integer
"passedTestCases": integer // Number of test cases that passed
"metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
"evaluationConfig": object
"progressPercentage": number (double)
"overallScore": number (double)
"passRate": number (double)
"averageExecutionTimeMs": integer
"totalExecutionTimeMs": integer
"chatbotConfig": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"insights":
{
"summary": string
"metricStats"?: object // Optional
"recommendations"?: object // Optional
}
}
]
}
```
**Example Response Values**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"evaluationLlm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"status": {},
"startedAt": "Response string",
"completedAt": "Response string",
"totalTestCases": 456,
"completedTestCases": 456,
"passedTestCases": 456,
"metricScores": null,
"evaluationConfig": null,
"progressPercentage": 456,
"overallScore": 456,
"passRate": 456,
"averageExecutionTimeMs": 456,
"totalExecutionTimeMs": 456,
"chatbotConfig": "Response string",
"createdAt": "Response string",
"updatedAt": "Response string",
"insights": {
"summary": "Response string",
"metricStats": null,
"recommendations": null
}
}
]
}
```
***
### Get Evaluation Result
GET `/api/v1/evaluations/{id}/`
{% hint style="info" %}
`status` is one of `pending`, `running`, `stopping`, `completed`, `partial_completed`, or `failed`. While running, check `progressPercentage`; once finished, check `passRate`, `overallScore`, and the per-metric `metricScores`. If no test case completes, the evaluation ends as `failed`.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------- |
| `id` | ✅ | string | Evaluation ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"name": string
"description": string
"chatbot":
{
"id": string (uuid)
"name": string
}
"dataset":
{
"id": string (uuid)
"name": string
}
"organization":
{
"id": string (uuid)
"name": string
}
"evaluationLlm":
{
"id": string (uuid)
"name": string
}
"status":
{
}
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"totalTestCases": integer
"completedTestCases": integer
"passedTestCases": integer // Number of test cases that passed
"metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
"evaluationConfig": object
"progressPercentage": number (double)
"overallScore": number (double)
"passRate": number (double)
"averageExecutionTimeMs": integer
"totalExecutionTimeMs": integer
"chatbotConfig": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"insights":
{
"summary": string
"metricStats"?: object // Optional
"recommendations"?: object // Optional
}
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"evaluationLlm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"status": {},
"startedAt": "Response string",
"completedAt": "Response string",
"totalTestCases": 456,
"completedTestCases": 456,
"passedTestCases": 456,
"metricScores": null,
"evaluationConfig": null,
"progressPercentage": 456,
"overallScore": 456,
"passRate": 456,
"averageExecutionTimeMs": 456,
"totalExecutionTimeMs": 456,
"chatbotConfig": "Response string",
"createdAt": "Response string",
"updatedAt": "Response string",
"insights": {
"summary": "Response string",
"metricStats": null,
"recommendations": null
}
}
```
***
### List Per-Question Results of a Single-Turn Evaluation
GET `/api/v1/evaluations/{id}/details/`
{% hint style="info" %}
Single-turn evaluations only; multi-turn evaluations return `400`. The response is an array of all test case results and is not paginated.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------- |
| `id` | ✅ | string | Evaluation ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
[
{
"id": string (uuid)
"datasetEvaluation":
{
"id": string (uuid)
"name": string
}
"testCase":
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // Optional
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (Optional)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (Optional)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (Optional)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (Optional)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"status":
{
}
"chatbotResponse": string
"context": [ // Enrich each context item with is_deleted status for referenced knowledge base files.
object
]
"metricScores": object
"executionTimeMs": integer
"executionTimeSeconds": number (double)
"passed": boolean
"errorMessage": string // Error message recorded when the evaluation fails
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"retryCount": integer // Number of times this test case has been retried
"lastAttemptAt": string (timestamp) // Time of the last evaluation attempt
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
```
**Example Response Values**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"datasetEvaluation": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"testCase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"question": "Response string",
"groundTruth": "Response string",
"status": "active",
"creationMethod": "manual",
"sourceFile": "Response string",
"flaky": false,
"createdAt": "Response string",
"updatedAt": "Response string"
},
"status": {},
"chatbotResponse": "Response string",
"context": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Example name",
"description": "Example description"
}
],
"metricScores": null,
"executionTimeMs": 456,
"executionTimeSeconds": 456,
"passed": false,
"errorMessage": "Response string",
"startedAt": "Response string",
"completedAt": "Response string",
"retryCount": 456,
"lastAttemptAt": "Response string",
"createdAt": "Response string",
"updatedAt": "Response string"
}
]
```
***
### List Per-Conversation Results of a Multi-Turn Evaluation
GET `/api/v1/evaluations/{id}/multi-turn-results/`
{% hint style="info" %}
Multi-turn evaluations only; single-turn evaluations return `400`. The response is paginated.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------- | ----------------------------------------------------------------------------- |
| `id` | ✅ | string | Evaluation ID |
| `page` | ❌ | integer | Page number, starting from 1; a page beyond the last page returns 404 |
| `pageSize` | ❌ | integer | Items per page. Default 20, maximum 100 (values above 100 are treated as 100) |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?page=1&pageSize=1" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?page=1&pageSize=1", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?page=1&pageSize=1"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?page=1&pageSize=1", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
{
"count": integer
"next"?: string (uri) // Optional
"previous"?: string (uri) // Optional
"results": [
{
"id": string (uuid)
"multiTurnTestCase": string (uuid)
"scenario": string
"expectedOutcome": string
"flaky": boolean
"status":
{
}
"turns": object // The whole simulated conversation; each turn is {role, content, retrieval_context}
"metricScores": object
"passed": boolean
"errorMessage": string
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"createdAt": string (timestamp)
}
]
}
```
**Example Response Values**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"multiTurnTestCase": "550e8400-e29b-41d4-a716-446655440000",
"scenario": "Response string",
"expectedOutcome": "Response string",
"flaky": false,
"status": {},
"turns": null,
"metricScores": null,
"passed": false,
"errorMessage": "Response string",
"startedAt": "Response string",
"completedAt": "Response string",
"createdAt": "Response string"
}
]
}
```
***
### Cancel a Running Evaluation
POST `/api/v1/evaluations/{id}/cancel/`
{% hint style="info" %}
Only evaluations whose `status` is `running` can be canceled; otherwise `400` is returned. After cancellation, `status` first becomes `stopping` and ends as `partial_completed` once stopped. Scores already calculated are kept, and completed test cases still consume Credit as usual. You can later run the remaining test cases with [Resume an incomplete evaluation](#evaluations-resume-create).
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------- |
| `id` | ✅ | string | Evaluation ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Make sure to replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request body (payload)
const data = null;
axios.post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.post(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"name": string
"description": string
"chatbot":
{
"id": string (uuid)
"name": string
}
"dataset":
{
"id": string (uuid)
"name": string
}
"organization":
{
"id": string (uuid)
"name": string
}
"evaluationLlm":
{
"id": string (uuid)
"name": string
}
"status":
{
}
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"totalTestCases": integer
"completedTestCases": integer
"passedTestCases": integer // Number of test cases that passed
"metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
"evaluationConfig": object
"progressPercentage": number (double)
"overallScore": number (double)
"passRate": number (double)
"averageExecutionTimeMs": integer
"totalExecutionTimeMs": integer
"chatbotConfig": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"insights":
{
"summary": string
"metricStats"?: object // Optional
"recommendations"?: object // Optional
}
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"evaluationLlm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"status": {},
"startedAt": "Response string",
"completedAt": "Response string",
"totalTestCases": 456,
"completedTestCases": 456,
"passedTestCases": 456,
"metricScores": null,
"evaluationConfig": null,
"progressPercentage": 456,
"overallScore": 456,
"passRate": 456,
"averageExecutionTimeMs": 456,
"totalExecutionTimeMs": 456,
"chatbotConfig": "Response string",
"createdAt": "Response string",
"updatedAt": "Response string",
"insights": {
"summary": "Response string",
"metricStats": null,
"recommendations": null
}
}
```
***
### Resume Incomplete Evaluation
POST `/api/v1/evaluations/{id}/resume/`
{% hint style="info" %}
Only evaluations whose `status` is `partial_completed` can be resumed; otherwise `400` is returned. Failed and not-yet-run test cases are re-run while completed results are kept, and `202` is returned; Credits are deducted only for completed cases that were not previously billed.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------- |
| `id` | ✅ | string | Evaluation ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request body (payload)
const data = null;
axios.post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.post(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 202**
**Example Response Structure**
```typescript
{
"status": string (enum: accepted) // * `accepted` - Always accepted, indicating the request has been accepted and queued for background execution
"message": string // Acceptance description
"taskId": string // Background task ID
}
```
**Example Response Values**
```json
{
"status": "accepted",
"message": "Response string",
"taskId": "Response string"
}
```
***
### Export Evaluation Report
POST `/api/v1/evaluations/{id}/export/`
{% hint style="info" %}
Only single-turn evaluations whose `status` is `completed` can be exported; multi-turn evaluations are not currently supported and return `400`. The report is generated as an Excel file in the background, and `201` is returned with the export record. Then use [Get Latest Export Status](#evaluations-export-status-retrieve) to get the download URL.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------- |
| `id` | ✅ | string | Evaluation ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request body (payload)
const data = null;
axios.post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.post(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 201**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"userEmail": string (email)
"datasetEvaluationId": string (uuid)
"datasetEvaluationName": string
"status":
{
}
"statusDisplay": string
"fileUrl": string // Returns the file URL
"fileSize": integer // File size in bytes
"errorMessage": string
"processingDurationSeconds": number (double) // Calculated processing duration (seconds)
"createdAt": string (timestamp)
"startedAt": string (timestamp)
"completedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userEmail": "response@example.com",
"datasetEvaluationId": "550e8400-e29b-41d4-a716-446655440000",
"datasetEvaluationName": "Response string",
"status": {},
"statusDisplay": "Response string",
"fileUrl": "Response string",
"fileSize": 456,
"errorMessage": "Response string",
"processingDurationSeconds": 456,
"createdAt": "Response string",
"startedAt": "Response string",
"completedAt": "Response string"
}
```
***
### Get Latest Export Status
GET `/api/v1/evaluations/{id}/export-status/`
{% hint style="info" %}
Returns the most recent export record for this evaluation: `status` is `pending`, `processing`, `completed`, or `failed`; when `completed`, download from `fileUrl`. If this evaluation has no export record, `404` is returned.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------- |
| `id` | ✅ | string | Evaluation ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"userEmail": string (email)
"datasetEvaluationId": string (uuid)
"datasetEvaluationName": string
"status":
{
}
"statusDisplay": string
"fileUrl": string // Returns the file URL
"fileSize": integer // File size in bytes
"errorMessage": string
"processingDurationSeconds": number (double) // Calculated processing duration (seconds)
"createdAt": string (timestamp)
"startedAt": string (timestamp)
"completedAt": string (timestamp)
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userEmail": "response@example.com",
"datasetEvaluationId": "550e8400-e29b-41d4-a716-446655440000",
"datasetEvaluationName": "Response string",
"status": {},
"statusDisplay": "Response string",
"fileUrl": "Response string",
"fileSize": 456,
"errorMessage": "Response string",
"processingDurationSeconds": 456,
"createdAt": "Response string",
"startedAt": "Response string",
"completedAt": "Response string"
}
```
***
### List Export Records
GET `/api/v1/evaluations/{id}/exports/`
{% hint style="info" %}
The response is an array of all export records for this evaluation, sorted from newest to oldest, without pagination.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------- |
| `id` | ✅ | string | Evaluation ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/", config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
[
{
"id": string (uuid)
"userEmail": string (email)
"datasetEvaluationId": string (uuid)
"datasetEvaluationName": string
"status":
{
}
"statusDisplay": string
"fileUrl": string // Returns the file URL
"fileSize": integer // File size in bytes
"processingDurationSeconds": number (double) // Calculated processing duration (seconds)
"createdAt": string (timestamp)
"startedAt": string (timestamp)
"completedAt": string (timestamp)
}
]
```
**Example Response Values**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userEmail": "response@example.com",
"datasetEvaluationId": "550e8400-e29b-41d4-a716-446655440000",
"datasetEvaluationName": "Response string",
"status": {},
"statusDisplay": "Response string",
"fileUrl": "Response string",
"fileSize": 456,
"processingDurationSeconds": 456,
"createdAt": "Response string",
"startedAt": "Response string",
"completedAt": "Response string"
}
]
```
***
### Edit Evaluation Name and Description
PATCH `/api/v1/evaluations/{id}/`
{% hint style="info" %}
Only `name` and `description` are accepted; other fields are ignored. Evaluations can be edited in any status.
{% endhint %}
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------- |
| `id` | ✅ | string | Evaluation ID |
#### Request Content
**Request Parameters**
| Field | Type | Required | Description |
| ----------- | ------ | -------- | ----------- |
| name | string | No | |
| description | string | No | |
**Example Request Structure**
```typescript
{
"name"?: string // Optional
"description"?: string // Optional
}
```
**Example Request Values**
```json
{
"name": "Example name",
"description": "Example string"
}
```
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example name",
"description": "Example string"
}'
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// Request body (payload)
const data = {
"name": "Example name",
"description": "Example string"
};
axios.patch("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# Request body (payload)
data = {
"name": "Example name",
"description": "Example string"
}
response = requests.patch(url, json=data, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => 'Example name',
'description' => 'Example string'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
**Status code: 200**
**Example Response Structure**
```typescript
{
"id": string (uuid)
"name": string
"description": string
"chatbot":
{
"id": string (uuid)
"name": string
}
"dataset":
{
"id": string (uuid)
"name": string
}
"organization":
{
"id": string (uuid)
"name": string
}
"evaluationLlm":
{
"id": string (uuid)
"name": string
}
"status":
{
}
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"totalTestCases": integer
"completedTestCases": integer
"passedTestCases": integer // Number of test cases that passed
"metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
"evaluationConfig": object
"progressPercentage": number (double)
"overallScore": number (double)
"passRate": number (double)
"averageExecutionTimeMs": integer
"totalExecutionTimeMs": integer
"chatbotConfig": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"insights":
{
"summary": string
"metricStats"?: object // Optional
"recommendations"?: object // Optional
}
}
```
**Example Response Values**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string",
"description": "Response string",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"evaluationLlm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Response string"
},
"status": {},
"startedAt": "Response string",
"completedAt": "Response string",
"totalTestCases": 456,
"completedTestCases": 456,
"passedTestCases": 456,
"metricScores": null,
"evaluationConfig": null,
"progressPercentage": 456,
"overallScore": 456,
"passRate": 456,
"averageExecutionTimeMs": 456,
"totalExecutionTimeMs": 456,
"chatbotConfig": "Response string",
"createdAt": "Response string",
"updatedAt": "Response string",
"insights": {
"summary": "Response string",
"metricStats": null,
"recommendations": null
}
}
```
***
### Delete Evaluation
DELETE `/api/v1/evaluations/{id}/`
#### Parameters
| Parameter Name | Required | Type | Description |
| -------------- | -------- | ------ | ------------- |
| `id` | ✅ | string | Evaluation ID |
#### Code Examples
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# Replace YOUR_API_KEY and verify the request data before running.
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// Set request headers
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// Request body (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('Response received successfully:');
console.log(response.data);
})
.catch(error => {
console.error('Request error:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("Response received successfully:")
print(response.json())
except Exception as e:
print("Request error:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "Response received successfully:\n";
print_r($data);
} catch (Exception $e) {
echo 'Request error: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### Response Content
| Status Code | Description |
| ----------- | ---------------- |
| 204 | No response body |
***
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/api/en/api-reference/ping-gu-he-ce-shi-ji.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.