---
title: "Start a workflow test run"
description: "Spends workspace credits. Only the user who started a run can read it."
url: https://docs.spinrun.ai/api/runs/test-workflow
markdown_url: https://docs.spinrun.ai/api/runs/test-workflow.md
---

# Start a workflow test run

Spends workspace credits. Only the user who started a run can read it.

## POST /api/build/workflows/{ref}/test

Start a workflow test run

Spends workspace credits. Only the user who started a run can read it.

Operation id: `testWorkflow`

### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| ref | path | yes | string | Agent or workflow id or slug. |

### Request body

`application/json`

```json
{
  "type": "object",
  "properties": {
    "input": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "description": "Start a workflow test run."
}
```

### Responses

| Status | Description |
|---|---|
| 202 | Accepted by the runtime. |
| 400 | Malformed JSON, a document that fails validation, or a field that contradicts the URL. |
| 401 | No or invalid token. The `WWW-Authenticate` header names the authorization server. |
| 403 | The grant has no Build authorization. |
| 404 | No such agent, workflow or run visible to this token. |
| 409 | The runtime refused the run (`run_id` names the row that recorded it), or the agent is archived. |
| 413 | Body over the document limit (64 KiB). |

#### 202 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "accepted": {
          "type": "boolean",
          "const": true
        },
        "run_id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "description": "The runtime's status at acceptance; poll GET /workflow-runs/{runId}."
        },
        "error": {
          "type": "string"
        }
      },
      "required": [
        "accepted",
        "run_id",
        "status"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false
}
```

#### 400 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 401 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 403 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 404 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```

#### 409 · `application/json`

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string"
        },
        "run_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "error",
        "run_id"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "additionalProperties": false
    }
  ]
}
```

#### 413 · `application/json`

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false
}
```