> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalvalidation.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List validation Runs

> Requires the GV.APIReader application role, or a higher role (Owner > Contributor > Reader).

API · Runs

GET `/api/v1/runs`

Requires the GV.APIReader application role, or a higher role (Owner > Contributor > Reader).

Operation ID · list\_runs

## Request example

```bash theme={null}
curl --request GET \
  --url 'https://api.generalvalidation.com/api/v1/runs?limit=50&validationTestUuid=99999999-9999-4999-8999-999999999999&overallStatus=pending&scope=all&sortBy=startedAt&search=orders&direction=desc' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <access-token>'
```

## Authentication and access

* **Required role:** GV.APIReader
* **Data classification:** metadata
* **Side effects:** none

Use an authentication scheme declared below. Ordinary workloads use application tokens; signed-in users use delegated tokens and Organization membership. Activation and invitation acceptance require a person, and execution callbacks require their registered identity.

* Microsoft Entra delegated user token
* Microsoft Entra application token

## Parameters

### limit

query

`integer`

* **Default:** `50`

minimum: 1 · maximum: 100

### cursor

query

Opaque continuation cursor. Reuse it only with the same parent, filters, and direction that issued it.

`string | null`

Opaque continuation cursor. Reuse it only with the same parent, filters, and direction that issued it.

Any of

**Option 1: string**

`string`

maximum length: 2048

**Option 2: null**

`null`

### validationTestUuid

query

`string (uuid) | null`

Any of

**Option 1: string (uuid)**

`string (uuid)`

**Option 2: null**

`null`

### overallStatus

query

`string | null`

Any of

**Option 1: string**

`string`

* **Allowed values:** `"pending"`,`"running"`,`"pass"`,`"fail"`,`"no_results"`,`"error"`

**Option 2: null**

`null`

### scope

query

`string | null`

Any of

**Option 1: string**

`string`

* **Allowed values:** `"all"`,`"dataset_pair"`,`"dataset_pairs"`,`"validation_test"`,`"retry"`

**Option 2: null**

`null`

### sortBy

query

Sort by run name, status, test count, received result count, or start time.

`string`

Sort by run name, status, test count, received result count, or start time.

* **Allowed values:** `"name"`,`"status"`,`"tests"`,`"results"`,`"startedAt"`
* **Default:** `"startedAt"`

### search

query

Case-insensitive literal search of run name, scope label, single-test function, or Run UUID.

`string | null`

Case-insensitive literal search of run name, scope label, single-test function, or Run UUID.

Any of

**Option 1: string**

`string`

maximum length: 200

**Option 2: null**

`null`

### direction

query

`string`

* **Allowed values:** `"asc"`,`"desc"`
* **Default:** `"desc"`

## Responses

This guide summarizes response status codes and headers. Retrieve the deployed, authenticated OpenAPI document for the exact response body schemas and examples. The API also provides an authenticated Swagger UI; opening it in a browser does not automatically attach a bearer token.

Error responses use `application/problem+json`. The response's stable `code` and `type` map to the [error-code reference](/errors).

### 200

Successful Response

### 401

A valid Microsoft Entra bearer token is required.

### 403

The authenticated principal does not have the required role.

### 409

The operation conflicts with current resource or Azure state.

### 422

The request is syntactically valid but semantically invalid.

### 429

The bounded application request rate was exceeded.

#### Headers

* **Retry-After:** Seconds to wait before retrying. `integer`minimum: 1

### 503

A required dependency is temporarily unavailable.

#### Headers

* **Retry-After:** Seconds to wait before retrying. `integer`minimum: 1