> ## 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.
# List runs
> Lists runs newest first, paginated, filtered by agentId, testId, folderId and/or executionId. At least one filter is required; filters combine.
## OpenAPI
````yaml GET /AgentTestRun
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:
/AgentTestRun:
get:
tags:
- AgentTestRun
summary: List runs
description: >-
Lists runs newest first, paginated, filtered by agentId, testId,
folderId and/or executionId. At least one filter is required; filters
combine.
operationId: ListAgentTestRuns
parameters:
- name: X-Api-Key
in: header
description: Api key to pass as a ```X-Api-Key``` request header.
required: true
schema:
type: string
- name: AgentId
in: query
schema:
type: string
description: Every run of this agent
- name: TestId
in: query
schema:
type: string
description: Runs of this test
- name: FolderId
in: query
schema:
type: string
description: Runs of the tests of this folder
- name: ExecutionId
in: query
schema:
type: string
description: Runs created by one execution
- name: Page
in: query
schema:
type: integer
format: int32
- name: PageSize
in: query
schema:
type: integer
format: int32
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PublicTestRunPaginatedResponse'
'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:
PublicTestRunPaginatedResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PublicTestRun'
description: List of items for the current page
nullable: true
total:
type: integer
description: Total number of items across all pages
format: int32
pageNumber:
type: integer
description: Current page number
format: int32
pageSize:
type: integer
description: Number of items per page
format: int32
additionalProperties: false
description: Paginated response wrapper
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: {}
PublicTestRun:
type: object
properties:
id:
type: string
nullable: true
testId:
type: string
nullable: true
agentId:
type: string
nullable: true
kind:
$ref: '#/components/schemas/AgentTestKind'
executionId:
type: string
description: Execution (launch) this run was created by
nullable: true
attempt:
type: integer
description: >-
Position of this run among the repetitions of its test in the
execution (1..repetitions)
format: int32
status:
$ref: '#/components/schemas/TestRunStatus'
errorReason:
type: string
description: Human-readable reason when status is Error
nullable: true
errorDetail:
type: string
description: Technical detail of the error, for diagnosis
nullable: true
agentChangeId:
type: string
description: >-
Identifier of the latest change of the agent when the run was
launched
nullable: true
createdAt:
type: string
format: date-time
dispatchedAt:
type: string
format: date-time
nullable: true
finishedAt:
type: string
format: date-time
nullable: true
simulation:
$ref: '#/components/schemas/PublicSimulationResult'
classification:
$ref: '#/components/schemas/PublicClassificationResult'
additionalProperties: false
description: One run of a test inside an execution
AgentTestKind:
enum:
- Simulation
- Classification
type: string
TestRunStatus:
enum:
- Queued
- Running
- Passed
- Failed
- Error
- Cancelled
type: string
PublicSimulationResult:
type: object
properties:
transcript:
type: array
items:
$ref: '#/components/schemas/PublicChatMessage'
description: >-
Full conversation, including the agent opening message when there is
one
nullable: true
verdicts:
type: array
items:
$ref: '#/components/schemas/PublicCriterionVerdict'
description: One verdict per criterion, in the order of the test criteria
nullable: true
variablesUsed:
type: object
additionalProperties:
type: string
nullable: true
turns:
type: integer
description: Number of user/agent exchanges
format: int32
endReason:
type: string
description: agent_ended | user_ended | max_turns | error
nullable: true
additionalProperties: false
PublicClassificationResult:
type: object
properties:
tagProduced:
type: string
nullable: true
matches:
type: boolean
description: True when the produced tag equals the expected tag
additionalProperties: false
PublicChatMessage:
type: object
properties:
role:
type: string
description: '"user" or "assistant"'
nullable: true
text:
type: string
nullable: true
timestamp:
type: string
format: date-time
nullable: true
additionalProperties: false
description: One message of a conversation
PublicCriterionVerdict:
type: object
properties:
criterion:
type: string
nullable: true
passed:
type: boolean
reason:
type: string
nullable: true
score:
type: number
description: Score between 0 and 1 when available
format: double
nullable: true
additionalProperties: false
````