> ## Documentation Index > Fetch the complete documentation index at: https://docs.octavehq.com/llms.txt > Use this file to discover all available pages before exploring further. # Run a skill > Runs a Skill with a `request` in words — once, or once per `items` line (at most 200) — and returns the run at once; each run is a hosted, brand-checked document (an Asset link) made by the skill's agent, and costs the skill's base price (charged only when its document is published) plus its research tools as used, up to 1,000 credits all-in. The skill's agent interprets the request and each item (a company domain, a person's email, a deal or CRM id, options in words); MCP `skill_run` with `check: true` returns the skill's usage line. Poll `GET /api/v2/runs/{oId}`, or pass `callbackUrl` to be POSTed the finished run. A repeated `idempotencyKey` returns the run it started. ## OpenAPI ````yaml post /api/v2/skills/{key}/runs openapi: 3.0.0 info: version: 6.0.0 title: Octave API description: API for Octave workspace management and AI-powered content generation servers: - url: https://app.octavehq.com security: - ApiKeyAuth: [] paths: /api/v2/skills/{key}/runs: post: tags: - Run summary: Run a skill description: >- Runs a Skill with a `request` in words — once, or once per `items` line (at most 200) — and returns the run at once; each run is a hosted, brand-checked document (an Asset link) made by the skill's agent, and costs the skill's base price (charged only when its document is published) plus its research tools as used, up to 1,000 credits all-in. The skill's agent interprets the request and each item (a company domain, a person's email, a deal or CRM id, options in words); MCP `skill_run` with `check: true` returns the skill's usage line. Poll `GET /api/v2/runs/{oId}`, or pass `callbackUrl` to be POSTed the finished run. A repeated `idempotencyKey` returns the run it started. operationId: startSkillRun parameters: - schema: type: string minLength: 1 maxLength: 64 description: >- The skill: a workspace skill's oId (skl_ prefix) or a catalog skill's name (deal-coach, meeting-prep, abm, …). example: deal-coach required: true description: >- The skill: a workspace skill's oId (skl_ prefix) or a catalog skill's name (deal-coach, meeting-prep, abm, …). name: key in: path requestBody: content: application/json: schema: type: object properties: request: type: string maxLength: 8000 default: '' description: >- What you want from the skill, in words: who or what it is about and any options. The skill's agent interprets it; for items, it applies to each. items: type: array items: type: string minLength: 1 maxLength: 2000 minItems: 1 maxItems: 200 description: >- Run once per item (at most 200): each a line naming what that run is for ("acme.com", "jane@acme.com", "Acme renewal, crmo_…"). delivery: type: object properties: mode: type: string enum: - digest - per_item default: digest slack: type: object nullable: true properties: channel: type: object properties: id: type: string minLength: 1 name: type: string minLength: 1 required: - id - name default: null required: - channel webhook: type: object nullable: true properties: url: type: string maxLength: 2000 default: null required: - url description: >- Where results go besides the callback: a Slack channel and/or an https webhook, as one digest when the run finishes or per item. callbackUrl: type: string format: uri description: >- POSTed the finished run (status, counts, credits, every item) once its last item settles. idempotencyKey: type: string minLength: 1 maxLength: 120 description: >- A key for this run: a second call with it returns the same run. responses: '200': description: The run, queued content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' run: $ref: '#/components/schemas/Run' started: type: boolean description: >- False when an earlier run with the same idempotencyKey was returned instead of starting another. required: - _metadata - run - started '400': description: >- The skill cannot run, an item does not check, or the workspace cannot afford the run content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' message: type: string required: - _metadata - message deprecated: false components: schemas: Metadata: type: object properties: usage: type: number default: 0 example: 0 description: API usage requestId: type: string example: requestId description: Request ID message: type: string example: message description: Message timestamp: type: string example: '2021-01-01T00:00:00.000Z' description: Timestamp required: - requestId - timestamp Run: type: object properties: oId: type: string subject: oneOf: - type: object properties: kind: type: string enum: - skill skill: oneOf: - type: object properties: source: type: string enum: - catalog name: type: string minLength: 1 maxLength: 64 pattern: ^[a-z0-9][a-z0-9-]*$ required: - source - name additionalProperties: false - type: object properties: source: type: string enum: - workspace skillOId: type: string minLength: 1 maxLength: 64 required: - source - skillOId additionalProperties: false draft: type: boolean required: - kind - skill - type: object properties: kind: type: string enum: - prioritized_abm loopRunOId: type: string minLength: 1 required: - kind - loopRunOId - type: object properties: kind: type: string enum: - deal_deliverable opportunityOId: type: string minLength: 1 deliverable: type: string enum: - account_plan - one_pager - first_call_deck - magazine - follow_up_emails - re_engagement_plan actionKey: type: string required: - kind - opportunityOId - deliverable - actionKey subjectLabel: type: string request: type: string trigger: type: string enum: - manual - schedule - api - webhook - crm_event status: type: string enum: - queued - running - paused - succeeded - partial - failed - cancelled counts: type: object properties: total: type: integer pending: type: integer succeeded: type: integer failed: type: integer skipped: type: integer required: - total - pending - succeeded - failed - skipped credits: type: object properties: unitPrice: type: number quoted: type: number held: type: number charged: type: number required: - unitPrice - quoted - held - charged delivery: type: object properties: mode: type: string enum: - digest - per_item slack: type: object nullable: true properties: channel: type: object properties: id: type: string minLength: 1 name: type: string minLength: 1 required: - id - name required: - channel webhook: type: object nullable: true properties: url: type: string required: - url callbackUrl: type: string nullable: true required: - mode - slack - webhook - callbackUrl idempotencyKey: type: string nullable: true createdBy: type: object nullable: true properties: oId: type: string email: type: string required: - oId - email summary: type: object nullable: true properties: line: type: string deliveries: type: array items: type: object properties: destination: type: string ok: type: boolean message: type: string required: - destination - ok - message stoppedReason: type: string nullable: true required: - line - deliveries - stoppedReason error: type: string nullable: true pauseReason: type: string nullable: true enum: - user - deployment - null createdAt: type: string startedAt: type: string nullable: true finishedAt: type: string nullable: true required: - oId - subject - subjectLabel - request - trigger - status - counts - credits - delivery - idempotencyKey - createdBy - summary - error - pauseReason - createdAt - startedAt - finishedAt securitySchemes: ApiKeyAuth: type: apiKey in: header name: api_key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.