Overview

The Thunders CI API lets you queue test executions, poll their status, and retrieve structured reports (JUnit XML or JSON), all through 3 endpoints under /api/ci/.

API Endpoints

POST  https://api.thunders.ai/api/ci/run
GET   https://api.thunders.ai/api/ci/run/{runId}
GET   https://api.thunders.ai/api/ci/run/{runId}/report

Authentication

The API requires authentication using a Bearer token:

Authorization: Bearer YOUR_THUNDER_TEST_TOKEN

You must obtain a valid API token from the Thunders platform. This token should be stored securely as a secret in your environment or GitHub repository.

Where to find your API token

API tokens belong to the organization rather than to a single project, so one token works across every project in it. You need an admin role to create one.

Select your organization name at the top of the left sidebar to open the organization menu.
Select Settings.
Select API Tokens. The Organization API Tokens page lists every token with its status, when it was created and who created it.
Create a new token, and confirm when asked "Are you sure you want to create a new API token?".
Select Show to reveal the new token, then Copy.
Paste it straight into your secret store. Treat it like a password, because anyone holding it can queue runs against your organization.

To withdraw a token, select Revoke on its row. Revoking cannot be undone, and any pipeline still using that token starts receiving 401 Unauthorized, so issue the replacement first.

Learn more: Create / Revoke an API token

Headers

Header	Value	Description
`Authorization`	`Bearer YOUR_THUNDER_TEST_TOKEN`	Authentication token
`X-MS-API-ROLE`	`M2M`	Indicates a machine-to-machine API call
`Content-Type`	`application/json`	Specifies the request body format

POST /api/ci/run — Queue Test Runs

Queues test executions for one or more test cases and/or test sets. All runs are grouped under a shared runId. Returns URLs you can use to poll status and fetch the final report.

Request Body

At least one of testCaseIds or testSetIds must be provided. Both can be provided in the same request and in that case both will be run.

Example

{
  "projectId": "c8e34ec4-2464-43c7-8db8-1b3a47a22337",
  "testCaseIds": ["a836fadc-377a-46fe-96b0-21f37c626bf9"],
  "testSetIds": ["8eea2fd3-da6d-4434-a310-176be84c5646"],
  "environmentId": "eca24252-e566-40a8-b2b0-707b7efa85d8",
  "personaId": "70d0ac52-fe94-4d89-aba9-8ef28dd8c04c",
  "maxParallelism": 5,
  "maxRetries": 1,
  "browserSettings": { "location": "Paris", "resolution": "1440x900", "deviceType": "Desktop" }
}

Parameters

Parameter	Type	Required	Default	Description
`projectId`	`string` (UUID)	Yes	-	The unique identifier of the project.
`testCaseIds`	`array` (UUIDs)	No	-	List of test case IDs to run.
`testSetIds`	`array` (UUIDs)	No	-	List of test set IDs. Each set expands to its test cases.
`environmentId`	`string` (UUID)	Yes	-	The environment to use.
`personaId`	`string` (UUID)	Yes	-	The persona for test execution.
`maxParallelism`	`int`	No	4	Max parallel tests. `0` = maximum.
`maxRetries`	`int`	No	0	Retry attempts for failed tests (0-3).
`executionMode`	`string`	No	`parallel`	`parallel` or `sequential`. In `sequential`, units run one at a time in alphabetical order of their names.
`failureBehavior`	`string`	No	`continue`	`continue` or `stop`. Only applies when `executionMode = sequential`. `stop` cancels the remaining runs after the first test case that ends in failed, once its retries are exhausted.
`testAssetReferences`	`array`	No	-	Test asset refs for batch execution.
`browserSettings.location`	`string`	No	`"Paris"`	Geo cluster: Paris, London, Amsterdam, SanFrancisco, NewYork.
`browserSettings.browserType`	`string`	No	`"Chromium"`	Chromium, Chrome, Firefox, or Safari.
`browserSettings.deviceType`	`string`	No	`"Desktop"`	Desktop, Mobile, or Tablet.
`browserSettings.resolution`	`string`	No	`"1280x720"`	Viewport resolution (e.g., "1440x900").

Response — 202 Accepted

{
  "runId": "01966a3e-...",
  "statusUrl": "/api/ci/run/01966a3e-...",
  "reportUrl": "/api/ci/run/01966a3e-.../report"
}

GET /api/ci/run/{runId} — Poll Run Status

Returns aggregated status of all test runs. Poll until status is terminal (passed, failed, stopped, cancelled).

Response — 200 OK

{
  "runId": "01966a3e-...",
  "status": "running",
  "testCount": 5,
  "passedCount": 2,
  "failedCount": 0,
  "runningCount": 2,
  "queuedCount": 1,
  "startedAt": "2026-03-20T14:30:00Z",
  "endedAt": null,
  "durationMs": null
}

GET /api/ci/run/{runId}/report — Fetch Report

Returns the test execution report. Format depends on the Accept header:

Default (or application/xml): JUnit XML, compatible with Jenkins, GitHub Actions (dorny/test-reporter), GitLab, and others.
Accept: application/json: JSON report with structured data.

Error Handling

The API uses standard HTTP status codes:

202 Accepted: POST /api/ci/run — tests were successfully queued
200 OK: GET endpoints — request was successful
400 Bad Request: Malformed request or missing required parameters
401 Unauthorized: Authentication failed or token is invalid
403 Forbidden: Insufficient permissions
404 Not Found: No test runs found for the given runId
500 Internal Server Error: Unexpected server error

Using with GitHub Actions

Integrate the Thunders CI API with GitHub Actions to automate test execution in your CI/CD pipeline.

Example GitHub Action Workflow

name: Run Thunders Tests
on:
  workflow_dispatch:
permissions:
  contents: read
  checks: write
jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Queue Thunders CI Run
        id: trigger
        run: |
          set -euo pipefail
          RESP=$(curl -sS --fail-with-body -X POST https://api.thunders.ai/api/ci/run \
            -H "Authorization: Bearer ${{ secrets.THUNDER_TEST_TOKEN }}" \
            -H "X-MS-API-ROLE: M2M" \
            -H "Content-Type: application/json" \
            -d '{"projectId":"YOUR_PROJECT_ID","testSetIds":["YOUR_TEST_SET_ID"],"environmentId":"YOUR_ENVIRONMENT_ID","personaId":"YOUR_PERSONA_ID","maxParallelism":5,"maxRetries":1}')
          echo "status_url=$(echo "$RESP" | jq -r '.statusUrl')" >> $GITHUB_OUTPUT
          echo "report_url=$(echo "$RESP" | jq -r '.reportUrl')" >> $GITHUB_OUTPUT
      - name: Wait for completion
        id: run-tests
        run: |
          set -euo pipefail
          MAX_WAIT=5400; INTERVAL=30; ELAPSED=0
          while [ $ELAPSED -lt $MAX_WAIT ]; do
            RESP=$(curl -sS --fail-with-body \
              "https://api.thunders.ai${{ steps.trigger.outputs.status_url }}" \
              -H "Authorization: Bearer ${{ secrets.THUNDER_TEST_TOKEN }}" \
              -H "X-MS-API-ROLE: M2M")
            STATUS=$(echo "$RESP" | jq -r '.status')
            echo "[$ELAPSED s] status=$STATUS"
            case "$STATUS" in
              passed|failed|stopped|cancelled)
                echo "final_status=$STATUS" >> $GITHUB_OUTPUT; break;;
            esac
            sleep $INTERVAL; ELAPSED=$((ELAPSED+INTERVAL))
          done
      - name: Download JUnit report
        run: |
          curl -sS --fail-with-body \
            "https://api.thunders.ai${{ steps.trigger.outputs.report_url }}" \
            -H "Authorization: Bearer ${{ secrets.THUNDER_TEST_TOKEN }}" \
            -H "X-MS-API-ROLE: M2M" \
            -o test-results.xml
      - name: Publish test results
        uses: dorny/test-reporter@v1
        continue-on-error: true
        with:
          name: Thunders CI Results
          path: test-results.xml
          reporter: java-junit
      - name: Fail if tests did not pass
        if: steps.run-tests.outputs.final_status != 'passed'
        run: exit 1

Setting Up GitHub Secrets

Go to your GitHub repository
Navigate to Settings, then Secrets and variables, then Actions
Click "New repository secret"
Name: THUNDER_TEST_TOKEN
Value: Your Thunders API token
Click "Add secret"

Test Asset Batch

The Test Asset Batch feature allows you to run the same test case multiple times with different data variations by uploading CSV files as test assets. Each row in the CSV becomes a separate test run, enabling data-driven testing at scale.

How It Works

Upload CSV files as test assets to your project (via the Thunders web app or API)
Reference the CSV files in your API request using the testAssetReferences parameter
Each CSV row generates a separate test run with its own variable overrides and browser settings
All runs from the same batch are grouped under a shared batchId

With executionMode: sequential, each CSV row runs as an independent chain: the test cases within a row run one at a time in alphabetical order, while rows run in parallel. maxParallelism caps how many rows run at once. failureBehavior: stop is scoped to a single row.

The testAssetReferences Parameter

Add the testAssetReferences field to your request body:

{
  "projectId": "your-project-id",
  "testCaseIds": ["your-test-case-id"],
  "environmentId": "your-environment-id",
  "personaId": "your-persona-id",
  "testAssetReferences": ["FILE_MYDATA_CSV", "FILE_USERS_CSV"]
}

Reference format: When you upload a file named mydata.csv, its reference becomes FILE_MYDATA_CSV. The naming convention is FILE_<FILENAME>_<EXT> where the filename is uppercased, and special characters are replaced with underscores.

To know more about the batching feature check out this documentation

Combining Multiple CSV Files

You can pass multiple CSV references in the testAssetReferences array. Rows from all files are merged sequentially into a single batch with continuous indexing.

If browsers.csv has 3 rows and mobile.csv has 2 rows, the batch will contain 5 total runs indexed 1 through 5.

When you do not need a pipeline

If all you want is for a Test Set to run on a recurring rule, a Schedule does that inside Thunders, with no pipeline to maintain and no token to rotate. Open the Test Set, select the Schedules tab, and pick one of five frequencies from Hourly to Monthly.

Keep using CI when the run has to happen at a point in your delivery process, such as after a deployment or on a pull request, or when you need a run more often than once an hour. Hourly is the shortest interval a Schedule supports.

See How do I schedule a Test Set to run automatically?