---
title: "Trigger a case run"
method: POST
path: "/api/triggers/cases/{caseId}/run"
tags: ["Triggers – Cases"]
---

# Trigger a case run

`POST /api/triggers/cases/{caseId}/run`

## Request

- Base URL: `https://aximo.autify.com`
- URL: `https://aximo.autify.com/api/triggers/cases/{caseId}/run`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/autify/apis/aximo-api/docs/api/triggers/cases/:caseId/run/post.ts> (a function with typed inputs; its response is checked against the schema)

Starts a new test session for the specified test case. The case must have
**API access enabled** in its settings.

Returns a `sessionId` — poll `GET /api/triggers/cases/{caseId}/sessions/{sessionId}`
to track progress.

The session carries the case's tags, so `GET /api/sessions?tag=…` finds
it. Tags can't be set per run here; to label a run, give the case the
tags or run it in a plan with run tags.

## Path parameters

- `caseId` string, uuid, required

## Request body

- object
  - `model` 'default' | 'haiku' | 'sonnet' | 'kimi' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.5' | 'auto': Model to use for this run. Call `GET /api/models` for the values your organization can run — anything else is rejected with `400`, and the error carries the usable list in `availableModels`. When omitted, the `defaultModel` from that endpoint applies.
  - `hostnameOverrideIds` string[]: IDs of hostname overrides to apply for this run.
  - `userDeviceId` string, uuid: Run on a registered local device (BYOD) from `GET /api/devices/user`; overrides the device bound on the case. A desktop case needs a desktop platform (`windows`, `macos`, `linux`); a mobile case needs a phone whose platform matches the case (`platform` in the body or the saved config), and cannot be combined with `deviceArn`. A mobile case bound to a local phone in `apiMobileConfig` runs on that phone when this field and `deviceArn` are both omitted; the run fails pre-flight, naming the phone, if it is no longer registered. Requires the BYOD feature to be enabled for your organization.
  - `deviceArn` string: Encrypted device token from `GET /api/devices` (mobile only).
  - `deviceName` string: Override the device name (mobile only).
  - `platform` 'ANDROID' | 'IOS': Override the mobile platform.
  - `uploadArn` string: Encrypted upload token from `GET /api/uploads/{id}` (mobile only).
  - `uploadType` 'own_app' | 'existing' | 'sample': Override the upload type (mobile only).
  - `appName` string: Override the app name (mobile only).
  - `bundleId` string: Override the app bundle id to launch (mobile only; a local phone needs one to launch an app). Must match `apps[0].bundleId` when both are given. Omitted, the case's saved bundle id applies unless the request installs an app of its own (`uploadArn` or `apps`).
  - `runMode` 'agent' | 'replay': `replay` replays the case's stored script when a usable version exists and runs the agent otherwise (mobile Device Farm runs only; requires the replay feature). Omitted means `agent`.
  - `apps` object[]: Up to 3 apps to install for a mobile run. Takes precedence over the single-app fields (`uploadArn`/`uploadType`/`appName`); the first entry is the primary app.
    - `uploadArn` string, required: Encrypted upload token from `GET /api/uploads/{id}`.
    - `uploadType` 'own_app' | 'existing' | 'sample', required
    - `appName` string, nullable, required
    - `bundleId` string

## Response `201`

Case run triggered.

- object
  - `success` boolean, required
  - `sessionId` string, uuid, required

## Other responses

- `400`: Invalid request body — including a `model` this organization cannot run (the response then carries `availableModels`), an undecryptable `deviceArn`/`uploadArn`/`apps[].uploadArn` token (`details.path` names the slot), or a schema failure (`details` carries the zod error tree).
- `401`: Missing or invalid API key.
- `403`: API access is not enabled for this case; a local device (BYOD) was requested — via `userDeviceId` or the device bound on the case — while BYOD is not enabled for the organization; the organization has insufficient credits (`details.reason` is `insufficient_credits`); or the case is multi-device while that feature is not enabled.
- `404`: Test case, user device, or upload not found. For an upload — whether from a per-run override or the stored config — `details.path` names the slot (e.g. `apps[0].uploadArn`, `apiMultiDeviceConfig[1].apps[0].uploadArn`).
- `429`: Rate limit exceeded — e.g. the daily session limit was reached for the organization, or too many API requests were sent in a short window (retry after the number of seconds in the `Retry-After` header).
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/autify/apis/aximo-api.md) - [All operations](https://skmtc.dev/autify/apis/aximo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/autify/apis/aximo-api/revisions/590722011284?raw)