---
title: "Create Test Execution"
method: POST
path: "/v1/projects/{projectId}/test-executions"
tags: ["Test Execution"]
---

# Create Test Execution

`POST /v1/projects/{projectId}/test-executions`

Trigger test execution(s) for a given project.

**Scope determines which fields are required:**
- `scope=TEST` — provide a `tests` array of test file names (each ending in `.test.yaml`).
- `scope=PIPELINE` — provide a `pipelines` array of pipeline file names (each ending in `.orch.yaml` or `.tran.yaml`). All tests associated with those pipelines will run.
- `scope=PROJECT` — runs every test in the project; no `tests` or `pipelines` field needed.

`environmentName` is always required. `versionName`, `executionTag`, and `agentId` are optional and work with any scope.

## Path parameters

- `projectId` string, uuid, required

## Request body

- TestExecutionRequest
  - `agentId` string — Optional agent ID. If not specified, the default agent for the environment will be used
  - `environmentName` string, required — The environment to execute tests in
  - `executionTag` string — Optional tag to control execution concurrency
  - `pipelines` PipelineReference[] — Pipelines whose associated tests to execute (required when scope=PIPELINE)
    - `name` string, required — Name of the pipeline file (must end with .orch.yaml or .tran.yaml)
  - `scope` 'TEST' | 'PIPELINE' | 'PROJECT', required — Execution scope: TEST, PIPELINE, or PROJECT
  - `tests` TestReference[] — Tests to execute (required when scope=TEST)
    - `name` string, required — Name of the test file (must end with .test.yaml)
  - `versionName` string — Optional artifact version name to execute tests against

## Response `201`

Test execution created

- TestExecutionResponse
  - `testExecutionId` string — Server-generated identifier for the test execution

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `403` — Forbidden
- `500` — Unexpected error occurred
- `504` — Gateway timeout

---

[API](https://skmtc.net/maia/apis/maia-public-rest-api.md) · [All operations](https://skmtc.net/maia/apis/maia-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/maia/maia-public-rest-api/revisions/6239825f68eb/schema)