Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt

Use this file to discover all available pages before exploring further.

The Gatling Enterprise Edition public REST API lets you automate every aspect of load testing from outside the UI—triggering runs from CI pipelines, fetching real-time metrics during a run, polling for run completion, and retrieving aggregated results for custom dashboards. All API operations require an API token, and the full endpoint catalogue is available as an OpenAPI 3 specification at a publicly hosted Swagger UI.

​
Base URL

All API endpoints are served at: 
https://api.gatling.io/api/public

​
Authentication

Every request must include an Authorization header populated with a valid API token: 
Authorization: <your_api_token>
API tokens are sensitive credentials. Never expose them in client-side code, commit them to source control, or log them in CI output. Store tokens in a secrets manager and inject them as environment variables at runtime.
The required permission level varies by endpoint:
OperationMinimum permission
Read simulations, runs, reportsRead
Start a test runStart
Upload packages, create simulationsConfigure
Manage users, teams, tokensAdministrate
See API Tokens for instructions on creating tokens with the appropriate permissions.

​
Key endpoints

The following examples demonstrate common API usage patterns. Replace <your_api_token> with your actual token value and use the correct resource IDs from your organization.

​
List simulations

Retrieve all simulations accessible with the token’s permissions. 
curl -X GET "https://api.gatling.io/api/public/simulations" \
  -H "Authorization: <your_api_token>"
Response (200 OK): 
[
  {
    "id": "sim_01abc...",
    "name": "Checkout Flow",
    "teamId": "team_01xyz...",
    "packageId": "pkg_01def..."
  }
]

​
Start a test run

Trigger a new run for a simulation. Requires the Start permission. 
curl -X POST "https://api.gatling.io/api/public/simulations/start" \
  -H "Authorization: <your_api_token>" \
  -H "Content-Type: application/json" \
  -d '{"simulationId": "sim_01abc..."}'
Response (200 OK): 
{
  "runId": "run_01ghi...",
  "simulationId": "sim_01abc...",
  "status": "Building"
}

​
Get run status

Poll the status of a run to detect completion, failure, or timeout. 
curl -X GET "https://api.gatling.io/api/public/simulations/runs/<runId>/summary" \
  -H "Authorization: <your_api_token>"
Response (200 OK): 
{
  "runId": "run_01ghi...",
  "status": "Successful",
  "start": "2024-06-01T10:00:00Z",
  "end": "2024-06-01T10:15:00Z",
  "assertionsResult": "Passed"
}
Possible run status values:
StatusMeaning
BuildingThe run is being prepared
DeployingLoad generators are being provisioned
InjectingVirtual users are being injected (run is active)
SuccessfulThe run completed and all assertions passed
AssertionsFailedThe run completed but one or more assertions failed
TimeoutThe run was stopped after exceeding the maximum duration
BrokenThe run failed to start or crashed
StoppedThe run was manually stopped

​
Get run metrics

Retrieve aggregated metrics for a completed run. 
curl -X GET "https://api.gatling.io/api/public/simulations/runs/<runId>/metrics" \
  -H "Authorization: <your_api_token>"

​
Upload a package

Upload a simulation package artifact (ZIP file). Requires the Configure permission. 
curl -X PUT \
  --upload-file ./target/my-simulation.jar.zip \
  "https://api.gatling.io/api/public/artifacts/<packageId>/content?filename=my-simulation.jar.zip" \
  -H "Authorization: <your_api_token>"

​
CI/CD integration pattern

The typical CI/CD workflow uses three API calls in sequence:
1

Upload the new package

After your build step produces a packaged simulation artifact, upload it to Gatling Enterprise with a PUT to the artifacts endpoint.
2

Start the run

POST to /simulations/start with the simulation ID. Store the returned runId.
3

Poll for completion

Repeatedly GET /simulations/runs/<runId>/summary with a sleep interval until the status field is a terminal value (Successful, AssertionsFailed, Timeout, Broken, Stopped). Exit the CI step with a non-zero code if the status is anything other than Successful.
The official Gatling build plugins (Maven, Gradle, sbt, and JavaScript CLI) implement this polling loop for you and integrate directly with standard CI platforms. Use the plugins rather than raw API calls whenever possible to benefit from automatic retry logic, log streaming, and report URL output.

​
OpenAPI specification

The complete, authoritative API reference is available as an OpenAPI 3 document:

OpenAPI Specification

View or download the full Gatling Enterprise OpenAPI 3 spec at https://gatling.github.io/gatling-enterprise-api/openapi/openapi.json
You can import this URL directly into tools such as Swagger UI, Postman, or Insomnia to explore and test every endpoint interactively.

​
Error handling

The API uses standard HTTP status codes:
CodeMeaning
200Success
400Bad request — check the request body or query parameters
401Unauthorized — missing or invalid Authorization header
403Forbidden — token does not have sufficient permissions for this operation
404Not found — the specified resource ID does not exist or is not accessible
429Too many requests — rate limit exceeded; back off and retry
500Internal server error — contact Gatling support if this persists

Build docs developers (and LLMs) love

Get started for freeTalk to us