---
title: "Run a skill"
description: "Run one saved skill. It starts the same agent run POST /v1/agent/completions starts, over the skill's own prompt, under the same two caps, and it is read at /v1/agent-runs/{id}.\n\nSend `quote_only: true` first to see the ceiling for free."
url: https://docs.roasos.com/api-reference/skills/runSkill
---

# Run a skill

Run one saved skill. It starts the same agent run POST /v1/agent/completions starts, over the skill's own prompt, under the same two caps, and it is read at /v1/agent-runs/{id}.

Send `quote_only: true` first to see the ceiling for free.

## `POST /v1/skills/{id}/runs`

Endpoint: `POST https://api.roasos.com/v1/skills/{id}/runs`

Run a skill

Run one saved skill. It starts the same agent run POST /v1/agent/completions starts, over the skill's own prompt, under the same two caps, and it is read at /v1/agent-runs/{id}.

Send `quote_only: true` first to see the ceiling for free.

### Parameters

- `id` (path) — required
- `undefined`
- `undefined`
- `undefined`

### Request body

Content type: `application/json`

### Responses

- `200`: A ceiling quote. Nothing is reserved and nothing runs.
- `202`: Run accepted. Poll /v1/agent-runs/{id}/status.
- `400`: validation_error, quote_required, a missing Idempotency-Key, or spend_cap_exceeds_policy
- `402`: insufficient_credits, or approval_required when a cap exceeds this key's unattended limit
- `404`: Skill not found in this workspace
- `409`: The idempotency key was reused with different request data
- `410`: quote_expired: the quote must be replaced under a new idempotency key
- `429`: rate_limit_exceeded, or a daily or monthly credit budget
- `503`: The run could not be recorded or started safely

Read the full reference at https://docs.roasos.com/api-reference/skills/runSkill.