Test Runs

Test runs are the core API resource. Submit a prompt, TesterArmy runs it in a real browser, and you get structured results back.

Submit a test run

POST /runs

Returns immediately with a run ID. Poll GET /runs/{id} or provide a webhookUrl to get notified on completion.

Request body

Field	Type	Required	Description
`prompt`	string	Yes	What to test. Include the target URL in your prompt.
`credentials`	array	No	Array of `{ username, password }` objects for authentication.
`webhookUrl`	string	No	URL to receive a POST when the run completes.

Example request

curl -X POST https://tester.army/api/v1/runs \
  -H "Authorization: Bearer sk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Go to https://example.com/pricing. Click the Pro plan Get Started button. Confirm the checkout page loads.",
    "webhookUrl": "https://your-app.com/webhooks/testerarmy"
  }'

Response (202)

{
  "id": "c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2",
  "status": "queued",
  "createdAt": "2026-02-12T00:00:00.000Z"
}

Get a test run

GET /runs/{id}

Response (200)

{
  "id": "c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2",
  "type": "chat",
  "status": "completed",
  "input": {
    "prompt": "Go to https://example.com/pricing. Click the Pro plan Get Started button."
  },
  "output": {
    "featureName": "Pricing Checkout",
    "result": "PASS",
    "description": "Checkout page loaded with the correct Pro plan.",
    "issues": [],
    "screenshots": ["https://tester.army/screenshots/abc123.png"]
  },
  "error": null,
  "durationMs": 12345,
  "webhookUrl": "https://your-app.com/webhooks/testerarmy",
  "webhookStatus": "delivered",
  "createdAt": "2026-02-12T00:00:00.000Z",
  "startedAt": "2026-02-12T00:00:01.000Z",
  "completedAt": "2026-02-12T00:00:12.000Z"
}

Run statuses: queued, running, completed, failed, cancelled.

List test runs

GET /runs

Query parameters

Field	Type	Default	Description
`limit`	number	10	Max results per page (max 100).
`status`	string	-	Filter: `queued`, `running`, `completed`, `failed`, `cancelled`.
`cursor`	string	-	Cursor from a previous response for pagination.

Response (200)

{
  "runs": [
    {
      "id": "c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2",
      "type": "chat",
      "status": "completed",
      "input": {
        "prompt": "Test the signup button on https://example.com"
      },
      "durationMs": 12345,
      "createdAt": "2026-02-12T00:00:00.000Z",
      "completedAt": "2026-02-12T00:00:12.000Z"
    }
  ],
  "nextCursor": "2026-02-12T00:00:00.000Z::c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2"
}

Cancel a test run

POST /runs/{id}/cancel

Only runs in queued status can be cancelled.

Response (200)

{
  "id": "c8e0f1b1-2f4c-4c2a-b6a6-8f76a6b9f1a2",
  "status": "cancelled"
}

Test Runs

On this page