---
schema_version: "1"
id: 09ffc3f885ed6ec816391f23b2d784e19a08d0501145155957bdecf5d3aa1a9b
title: Connect API Resources for Testing API
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/genai/agentforce/references/testing/testing-connect-reference.md
canonical_url: https://developer.salesforce.com/docs/ai/agentforce/references/testing-api/testing-connect-reference.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: a0e2bdfeba376c5974a1c88c9cc5f3069cd673f7dc60be3bce6fcfc94f51ae60
products:
  - Agentforce Developer Guide
  - Agentforce and Einstein Generative AI
---
# Connect API Resources for Testing API

The Connect API endpoints for Testing API execute test cases, poll for results, and programmatically retrieve detailed test results.

## Start Test

Start a test asynchronously based on the provided AiEvaluationDefinition name or ID. This endpoint schedules the test and returns an identifier to track its progress. OAuth 2.0 with a connected app is required. See the [Connect REST API Quick Start](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/quickstart.htm).

### Resource

```
/services/data/v63.0/einstein/ai-evaluations/runs
```

#### HTTP Methods

`POST`

### Request

#### Headers

```bash
{
"Content-Type": "application/json",
"Authorization": "Bearer <access_token>"
}
```

#### Parameters

```bash
{
"aiEvaluationDefinitionName": "<string>"
}
```

The API enforces that exactly one of the two parameters is provided. If no parameters or multiple parameters are provided, the API returns a `400 Bad Request` response code with an empty error message.

| Parameter Name               | Type   | Description                                                           |
| :--------------------------- | :----- | :-------------------------------------------------------------------- |
| `aiEvaluationDefinitionName` | string | Required. The name (`DeveloperName`) of the test definition to start. |

### Response

HTTP response code: 200

```json
{
  "runId": "<string>",
  "status": "<string>"
}
```

| Parameter Name | Type   | Description                             |
| :------------- | :----- | :-------------------------------------- |
| `runId`        | string | The unique ID of the test that started. |

## Get Test Status

Retrieves the operational status of a specified test. We designed this endpoint to poll to monitor the progress of a test.

### Resource

```
/einstein/ai-evaluations/runs/:runId
```

#### HTTP Methods

`GET`

### Request

#### Headers

```bash
{
"Authorization": "Bearer <token>"
}
```

#### Parameters

| Parameter Name | Type   | Description                                   |
| :------------- | :----- | :-------------------------------------------- |
| `runId`        | string | Required. The unique identifier for the test. |

### Response

```json
{
  "status": "<enum>",
  "startTime": "<ISO 8601 timestamp>",
  "endTime": "<ISO 8601 timestamp>",
  "errorMessage": "<string>"
}
```

| Parameter Name | Type               | Description                                                                                                                                                                                                                                       |
| :------------- | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`       | enum               | <ul><li>NEW: The test was created but not yet started.</li><li>IN_PROGRESS: The test is currently executing.</li><li>COMPLETED: The test finished successfully.</li><li>ERROR: At least one test case encountered an operational error.</li></ul> |
| `startTime`    | ISO 8601 timestamp | The timestamp indicating when the test started.                                                                                                                                                                                                   |
| `endTime`      | ISO 8601 timestamp | The timestamp indicating when the test ended. `endTime` is null if the test hasn't ended yet.                                                                                                                                                     |
| `errorMessage` | string             | The details of the error if the status is ERROR. `errorMessage` is empty if no error occurred.                                                                                                                                                    |

## Get Test Results

Retrieve a detailed report of a test, including information on each test case and the results of all predetermined expectations.

### Resource

```
/einstein/ai-evaluations/runs/:runId/results
```

#### HTTP Methods

`GET`

### Request

#### Headers

```bash
{
"Authorization": "Bearer <token>"
}
```

#### Parameters

| Parameter Name | Type   | Description                                  |
| :------------- | :----- | :------------------------------------------- |
| `runId`        | string | Required. The unique identifier of the test. |

### Response

```json
{
  "status": "<ENUM(“NEW”, “IN_PROGRESS”, “COMPLETED”, “ERROR”)>",
  "subjectName": "<string>",
  "startTime": "<ISO 8601 timestamp|null>",
  "endTime": "<ISO 8601 timestamp|null>",
  "errorMessage": "<string|null>",
  "testCases": [
    {
      "status": "<ENUM(“NEW”, “IN_PROGRESS”, “COMPLETED”, “ERROR”)>",
      "testNumber": "<integer>",
      "startTime": "<ISO 8601 timestamp|null>",
      "endTime": "<ISO 8601 timestamp|null>",
      "errorMessage": "<string|null>",
      "inputs": {
        "utterance": "<string>"
      },
      "generatedData": {
        "actionsSequence": "<string[]|null>",
        "outcome": "<string|null>",
        "topic": "<string|null>"
      },
      "testResults": [
        {
          "name": "<string>",
          "actualValue": "<string|null>",
          "expectedValue": "<string|null>",
          "metricScore": "<ENUM('PASS','FAILED','HIGH','LOW','UNCERTAIN')|null>",
          "metricLabel": "<string|null>",
          "metricExplainability": "<string|null>",
          "status": "<ENUM(“NEW”, “IN_PROGRESS”, “COMPLETED”, “ERROR”)>",
          "startTime": "<ISO 8601 timestamp|null>",
          "endTime": "<ISO 8601 timestamp|null>",
          "errorCode": "<string|null>",
          "errorMessage": "<string|null>"
        }
      ]
    }
  ]
}
```

#### Response Object

| Parameter Name | Type               | Description                                                                                                                                                                                                                                       |
| :------------- | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`       | enum               | <ul><li>NEW: The test was created but not yet started.</li><li>IN_PROGRESS: The test is currently executing.</li><li>COMPLETED: The test finished successfully.</li><li>ERROR: At least one test case encountered an operational error.</li></ul> |
| `startTime`    | ISO 8601 timestamp | The timestamp indicating when the test started.                                                                                                                                                                                                   |
| `endTime`      | ISO 8601 timestamp | The timestamp indicating when the test ended. `endTime` is null if the test hasn't ended yet.                                                                                                                                                     |
| `errorMessage` | string             | The details of the error if the status is ERROR. `errorMessage` is empty if no error occurred.                                                                                                                                                    |
| `testCases`    | TestCaseObject     | Represents the test cases being evaluated.                                                                                                                                                                                                        |

#### testCase Object

| Parameter Name | Type                      | Description                                                                                                                                                                                                                                            |
| :------------- | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status         | enum                      | <ul><li>NEW: The test has been created but not yet started.</li><li>IN_PROGRESS: The test is currently executing.</li><li>COMPLETED: The test finished successfully.</li><li>ERROR: At least one test case encountered an operational error.</li></ul> |
| testNumber     | integer                   | The number of the test case.                                                                                                                                                                                                                           |
| subjectName    | string                    | A unique identifier for the subject. This should be the `DeveloperName` of the `AiEvalDefinition` entity.                                                                                                                                              |
| startTime      | ISO 8601 timestamp        | The timestamp indicating when the test started.                                                                                                                                                                                                        |
| endTime        | ISO 8601 timestamp        | The timestamp indicating when the test ended. `endTime` is null if the test hasn't ended yet.                                                                                                                                                          |
| errorMessage   | string                    | Details of the error if the status is ERROR. `errorMessage` is empty if no error occurred.                                                                                                                                                             |
| inputs         | InputsObject              | Represents the inputs sent to the agent.                                                                                                                                                                                                               |
| generatedData  | GeneratedDataObject       | Represents the data that was generated by the subject during the test and was used to evaluate the expectations.                                                                                                                                       |
| testResults    | array\[TestResultObject\] | Includes the results of each test.                                                                                                                                                                                                                     |

#### inputs Object

| Parameter Name | Type   | Description                      |
| :------------- | :----- | :------------------------------- |
| utterance      | string | The utterance sent to the agent. |

#### generatedData Object

| Parameter Name  | Type            | Description                                      |
| :-------------- | :-------------- | :----------------------------------------------- |
| actionsSequence | array\[string\] | A sequence of actions performed during the test. |
| outcome         | string          | The response of the subject under test.          |
| topic           | string          | The subagent used by the subject during testing.    |

#### testResult Object

| Parameter Name       | Type               | Description                                                                                                                                                                                                                                        |
| :------------------- | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                 | string             | The name of the test metric.                                                                                                                                                                                                                       |
| actualValue          | string             | The actual value obtained during the test.                                                                                                                                                                                                         |
| expectedValue        | string             | The expected value for the metric.                                                                                                                                                                                                                 |
| metricScore          | enum               | The outcome for the metric. Values: `PASS`, `FAILED`. For `instruction_adherence` only: `HIGH`, `LOW`, `UNCERTAIN`.                                                                                                                                |
| metricLabel          | string             | The metric name.                                                                                                                                                                                                                                   |
| metricExplainability | string             | A detailed explanation of the metric's purpose and test criteria.                                                                                                                                                                                  |
| metricType           | string             | The name of the test metric.                                                                                                                                                                                                                       |
| status               | string             | <ul><li>NEW: The test has been created but not yet started</li><li>IN_PROGRESS: The test is currently executing</li><li>COMPLETED: The test finished successfully</li><li>ERROR: At least one test case encountered an operational error</li></ul> |
| startTime            | ISO 8601 timestamp | The timestamp when the test of this metric started.                                                                                                                                                                                                |
| endTime              | ISO 8601 timestamp | The timestamp when the test of this metric ended.                                                                                                                                                                                                  |
| errorCode            | string or null     | The error code if an error occurred during the test; otherwise, null.                                                                                                                                                                              |
| errorMessage         | string or null     | A detailed error message if an error occurred during the test; otherwise, null.                                                                                                                                                                    |