> ## Documentation Index > Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt > Use this file to discover all available pages before exploring further. # Run a workflow > Execute a workflow. Returns immediately with a `run_id`/`thread_id`; the workflow runs in the background (track progress via the run/listen surfaces). Subject to the synchronous billing admission gate (reject-before-write): an exhausted credit allowance, exceeded quota, or rate limit returns a flat `DenialEnvelope` with status 402/403/429 and no run is created. The workflow must have an active deployment. ## OpenAPI ````yaml /api-reference/openapi.json post /workflows/run openapi: 3.0.3 info: title: ModuleX API version: 0.1.2 description: >- ModuleX REST API. Authenticate with a user API key (`Authorization: Bearer mx_live_*`, or the `X-API-KEY` header) and supply the organization context header `X-Organization-ID` on org-scoped endpoints. Routers carry NO `/v1` version segment. Billing-gated surfaces (workflow run, managed knowledge search) reject before any write with a flat `DenialEnvelope` (402/403/429). servers: - url: https://api.modulex.dev description: Production security: - bearerAuth: [] orgHeader: [] tags: - name: Workflows description: Create, read, update and delete workflow definitions. - name: Runs description: Execute workflows. Subject to the billing admission gate. - name: Schedules description: Recurring (cron / interval) workflow executions. - name: Knowledge description: Knowledge bases and semantic search. - name: Credentials description: Integration credentials (API key, bearer, OAuth2, ModuleX-managed). - name: Integrations description: Catalog of available tools, LLM providers and knowledge providers. - name: Organizations description: Organization management. - name: API keys description: User-owned API keys for programmatic access. paths: /workflows/run: post: tags: - Runs summary: Run a workflow description: >- Execute a workflow. Returns immediately with a `run_id`/`thread_id`; the workflow runs in the background (track progress via the run/listen surfaces). Subject to the synchronous billing admission gate (reject-before-write): an exhausted credit allowance, exceeded quota, or rate limit returns a flat `DenialEnvelope` with status 402/403/429 and no run is created. The workflow must have an active deployment. operationId: runWorkflow requestBody: required: true content: application/json: schema: type: object required: - workflow_id properties: workflow_id: type: string format: uuid description: The workflow to execute. input: type: object description: Run inputs matching the workflow state schema. responses: '200': description: Run accepted and started in the background. content: application/json: schema: $ref: '#/components/schemas/RunAccepted' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/CreditExhausted' '403': $ref: '#/components/responses/QuotaExceeded' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: schemas: RunAccepted: type: object description: Acknowledgement that the run started in the background. properties: status: type: string example: running run_id: type: string format: uuid thread_id: type: string nullable: true chat_id: type: string format: uuid nullable: true description: Null when ephemeral=true. ephemeral: type: boolean stream: type: boolean workflow_name: type: string workflow_version: type: string nullable: true workflow_source: type: string example: database description: 'One of: database, request, system:.' elapsed_ms: type: number human_message: type: object nullable: true additionalProperties: true ai_message: type: object nullable: true additionalProperties: true message: type: string Error: type: object description: Standard FastAPI error response. properties: detail: description: >- Human-readable error message, or a structured object (some endpoints return `{message, code, ...}`). oneOf: - type: string - type: object additionalProperties: true DenialEnvelope: type: object description: >- Flat billing/credit/rate/quota denial envelope emitted by the synchronous admission gate (reject-before-write). NO `detail` wrapper. Layer-to-status: `quota`→403, `rate`→429, `credit`/`wallet`→402. required: - code - layer properties: code: type: string description: Machine-stable denial code the client branches on. example: credit_plan_exhausted enum: - credit_plan_exhausted - wallet_overage_disabled - wallet_insufficient - upgrade_payment_failed - quota_exceeded - rate_limit_exceeded layer: type: string description: Which gate layer denied. enum: - rate - quota - credit - wallet key: type: string nullable: true description: >- The specific limit/counter key (e.g. `sync_exec`, `max_knowledge_bases`). current: type: number nullable: true description: Observed usage/count at denial time. limit: type: number nullable: true description: The limit that was hit. reason: type: string nullable: true description: >- Short reason token (e.g. `overage_disabled`, `insufficient_balance`). responses: BadRequest: description: The request was malformed or failed a business rule. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Authentication required or invalid. Provide `Authorization: Bearer ` or `X-API-KEY`. headers: WWW-Authenticate: schema: type: string description: Bearer content: application/json: schema: $ref: '#/components/schemas/Error' CreditExhausted: description: >- Plan credit allowance exhausted (and no wallet overage available). Flat `DenialEnvelope`, layer `credit`/`wallet`. content: application/json: schema: $ref: '#/components/schemas/DenialEnvelope' example: code: credit_plan_exhausted layer: credit key: null current: 1000 limit: 1000 reason: credit_plan_exhausted QuotaExceeded: description: A per-resource quota was hit. Flat `DenialEnvelope`, layer `quota`. content: application/json: schema: $ref: '#/components/schemas/DenialEnvelope' example: code: quota_exceeded layer: quota key: max_knowledge_bases current: 10 limit: 10 reason: quota_exceeded NotFound: description: The resource was not found (or is not in the caller's organization). content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Rate limit exceeded. Flat `DenialEnvelope`, layer `rate`. Includes `Retry-After` and `X-RateLimit-*` headers. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (defaults to 60). X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer description: Unix epoch seconds when the window resets. content: application/json: schema: $ref: '#/components/schemas/DenialEnvelope' example: code: rate_limit_exceeded layer: rate key: sync_exec current: null limit: 60 reason: rate_limit_exceeded securitySchemes: bearerAuth: type: http scheme: bearer description: >- User API key: `Authorization: Bearer mx_live_*`. The `X-API-KEY: mx_live_*` header is also accepted. orgHeader: type: apiKey in: header name: X-Organization-ID description: Required organization context for org-scoped endpoints. ````