> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starleads.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Launch tests
> Launches tests of one of your agents and returns the execution immediately. Give `testIds` to launch a selection, or omit it to launch every test of the agent; `repetitions` (1-5) runs each test several times. Poll the execution until its status is Completed or Cancelled.
## OpenAPI
````yaml POST /AgentTestExecution
openapi: 3.0.1
info:
title: Starleads public API documentation
description: >
Welcome to the Starleads Public API documentation. This API provides public
access to Starleads services, allowing developers and growth-hackers to
interact with campaign-related data.
***
### Base endpoint
```https://api.starleads.co```
***
### Errors
The API uses standard HTTP status codes to indicate the success or failure
of the API call. In case of failure, the body of the response will be JSON
in the following format:
```
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Bad Request",
"status": 400,
"detail": "No campaign exists with campaignId : 11111111"
}
```
The ```type``` property is a link to a general description of the error
type.
***
### Authentification
Authentication for the API is handled with an API key that must be provided
as a ```X-Api-Key``` header for every request.
**API keys are supposed to be a secret that only the client and server know.
Please remember to not share them with anyone.**
You can find your API keys when authenticated in your Starleads profile
:
version: v1
x-logo:
url: https://api.starleads.co/images/starleads-logo.png
servers: []
security: []
tags:
- name: Agent
description: >-
Manage your AI agent's prompt. These endpoints allow you to read and
update the prompt that drives your agent's behavior during calls.
- name: CampaignField
description: >-
CampaignFields enables users to specify customizable fields within their
campaigns. These fields serve as placeholders (e.g., ```{lastname}```)
that can be dynamically filled with corresponding data when creating
prompts, providing flexibility in tailoring campaign content based on
specific variables.
**Those are the keys of the ```databag``` field of
the request payload to add a new ```CampaignItem``` to a campaign.**
- name: CampaignItem
description: Represents prospects entries related to a campaign
- name: Consumption
description: >-
Track your company's credit consumption. These endpoints expose your
current balance, usage and billing period so you can build budget
monitoring on top of the API.
- name: Subscription
description: >-
Inspect your subscription contract: the plan you are on, your subscription
status, the features currently active and your effective limits. No
pricing information is exposed.
- name: AgentTest
description: >-
Tests of your agents: simulation tests (a simulated user talks to the
agent and each success criterion is judged) and classification tests (the
agent must produce the expected tag for a conversation). A test belongs to
one agent.
- name: AgentTestExecution
description: >-
Executions of agent tests: launching a set of tests, following their
progress and cancelling them. One execution groups the runs created
together for a list of tests, each repeated up to 5 times.
- name: AgentTestFolder
description: >-
Folders grouping the tests of an agent (flat, with a name, a color and a
markdown body).
- name: AgentTestRun
description: >-
Runs of agent tests: one run is one attempt of one test inside an
execution. Results, history and cancellation.
- name: SimulationChat
description: >-
Test an agent through a text chat, exactly as it would behave in a real
conversation (prompt, fields and connected tools included). Start a chat,
then exchange messages with the agent.
paths:
/AgentTestExecution:
post:
tags:
- AgentTestExecution
summary: Launch tests
description: >-
Launches tests of one of your agents and returns the execution
immediately. Give `testIds` to launch a selection, or omit it to launch
every test of the agent; `repetitions` (1-5) runs each test several
times. Poll the execution until its status is Completed or Cancelled.
operationId: CreateAgentTestExecution
parameters:
- name: X-Api-Key
in: header
description: Api key to pass as a ```X-Api-Key``` request header.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTestExecutionRequest'
text/json:
schema:
$ref: '#/components/schemas/CreateTestExecutionRequest'
application/*+json:
schema:
$ref: '#/components/schemas/CreateTestExecutionRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PublicTestExecution'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'422':
description: Client Error
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
schemas:
CreateTestExecutionRequest:
required:
- agentId
type: object
properties:
agentId:
minLength: 1
type: string
description: Agent owning the tests
name:
type: string
description: Free text naming the launch; defaults to "{n} tests"
nullable: true
testIds:
type: array
items:
type: string
description: >-
Tests of the agent to launch; absent or empty launches every test of
the agent
nullable: true
repetitions:
type: integer
description: Runs created per test, between 1 and 5; null means 1
format: int32
nullable: true
additionalProperties: false
description: >-
Tests to launch. Omit testIds (or leave it empty) to launch every test
of the agent.
PublicTestExecution:
type: object
properties:
id:
type: string
nullable: true
agentId:
type: string
nullable: true
name:
type: string
description: >-
Free text given at launch ("all tests", "folder X", ...); defaults
to "{n} tests"
nullable: true
repetitions:
type: integer
description: Runs created per test (1-5)
format: int32
testIds:
type: array
items:
type: string
description: Distinct tests launched, in launch order
nullable: true
status:
$ref: '#/components/schemas/TestExecutionStatus'
createdAt:
type: string
format: date-time
startedAt:
type: string
description: First run dispatched
format: date-time
nullable: true
finishedAt:
type: string
description: Last run finished, set once every run is terminal
format: date-time
nullable: true
cancelledAt:
type: string
description: Set when the execution was cancelled
format: date-time
nullable: true
counters:
$ref: '#/components/schemas/PublicTestExecutionCounters'
tests:
type: array
items:
$ref: '#/components/schemas/PublicTestExecutionTestSummary'
description: >-
Per test, in testIds order: runs per status and pass rate over the
repetitions
nullable: true
additionalProperties: false
description: >-
One launch: the group of runs created together for a list of tests, each
repeated `repetitions` times. Status, counters, tests, startedAt and
finishedAt are derived from the runs.
ProblemDetails:
type: object
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
nullable: true
detail:
type: string
nullable: true
instance:
type: string
nullable: true
additionalProperties: {}
TestExecutionStatus:
enum:
- Queued
- Running
- Completed
- Cancelled
type: string
PublicTestExecutionCounters:
type: object
properties:
total:
type: integer
format: int32
queued:
type: integer
format: int32
running:
type: integer
format: int32
passed:
type: integer
format: int32
failed:
type: integer
format: int32
error:
type: integer
format: int32
cancelled:
type: integer
format: int32
additionalProperties: false
description: Runs per status; total is the sum of the others
PublicTestExecutionTestSummary:
type: object
properties:
testId:
type: string
nullable: true
counters:
$ref: '#/components/schemas/PublicTestExecutionCounters'
passRate:
type: number
description: >-
Passed / (passed + failed + error), between 0 and 1; null while no
run has finished (cancelled runs are not counted)
format: double
nullable: true
additionalProperties: false
description: Outcome of one test inside an execution, over its repetitions
````