> ## Documentation Index > Fetch the complete documentation index at: https://docs.apiosk.com/llms.txt > Use this file to discover all available pages before exploring further. # Call a source (explicit form) > The same call with a named envelope. Requires sources:execute. ## OpenAPI ````yaml /openapi/apiosk-api.json post /v2/sources/{source_id}/run openapi: 3.1.0 info: title: Apiosk API version: 2.0.0 description: >- Buy verifiable data per call with an organisation API key. Discover sources, run one directly, or let Apiosk plan across sources. Amounts are USD; every amount carries an exact micro-USD integer. servers: - url: https://gateway.apiosk.com security: - apiKey: [] paths: /v2/sources/{source_id}/run: post: summary: Call a source (explicit form) description: The same call with a named envelope. Requires sources:execute. operationId: runSource parameters: - name: source_id in: path required: true schema: type: string example: kvk-dutch-business-register - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: 'Retry-safe key: the same key with the same body pays once.' example: nomi-request-983472 requestBody: required: true content: application/json: schema: type: object required: - operation properties: operation: type: string example: company_registry.search input: type: object additionalProperties: true example: company.name: Mollie B.V. max_spend: type: number example: 1 wait_seconds: type: integer minimum: 0 maximum: 55 responses: '200': description: Success content: application/json: schema: type: object properties: id: type: string format: uuid status: type: string enum: - requires_approval - running - completed - partial - needs_input - needs_selection - unsupported - cancelled - failed question: type: string plan: type: object properties: quote_ref: type: string format: uuid expires_at: type: string format: date-time steps: type: array items: type: object properties: source_id: type: string example: kvk-dutch-business-register operation: type: string example: company_registry.search name: type: string conditional: type: boolean estimated_cost: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD estimated_total: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD answer: type: - object - 'null' description: >- Apiosk's reading of the results, with evidence pointers. Null for a direct call. data: type: object description: The source document, when the run produced exactly one. results: type: array items: type: object properties: result_ref: type: string format: uuid source: type: object properties: provider: type: string name: type: string data: type: object usage: type: object properties: sources: type: array items: type: object properties: source_id: type: string operation: type: string calls: type: integer cost: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD cost: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD held: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD balance: type: object properties: remaining: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD errors: type: array items: type: object properties: code: type: string message: type: string retry_after_ms: type: integer message: type: - string - 'null' description: Natural-language clarification for needs_input. needs_input: type: array items: type: object properties: label: type: string schema: type: object candidates: type: - array - 'null' items: type: object approval_required_reason: type: object properties: code: type: string message: type: string metadata: type: object description: Attribution for a single result, when present. continuation: $ref: '#/components/schemas/Continuation' '202': description: Still running content: application/json: schema: type: object properties: id: type: string format: uuid status: type: string enum: - requires_approval - running - completed - partial - needs_input - needs_selection - unsupported - cancelled - failed question: type: string plan: type: object properties: quote_ref: type: string format: uuid expires_at: type: string format: date-time steps: type: array items: type: object properties: source_id: type: string example: kvk-dutch-business-register operation: type: string example: company_registry.search name: type: string conditional: type: boolean estimated_cost: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD estimated_total: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD answer: type: - object - 'null' description: >- Apiosk's reading of the results, with evidence pointers. Null for a direct call. data: type: object description: The source document, when the run produced exactly one. results: type: array items: type: object properties: result_ref: type: string format: uuid source: type: object properties: provider: type: string name: type: string data: type: object usage: type: object properties: sources: type: array items: type: object properties: source_id: type: string operation: type: string calls: type: integer cost: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD cost: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD held: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD balance: type: object properties: remaining: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD errors: type: array items: type: object properties: code: type: string message: type: string retry_after_ms: type: integer message: type: - string - 'null' description: Natural-language clarification for needs_input. needs_input: type: array items: type: object properties: label: type: string schema: type: object candidates: type: - array - 'null' items: type: object approval_required_reason: type: object properties: code: type: string message: type: string metadata: type: object description: Attribution for a single result, when present. continuation: $ref: '#/components/schemas/Continuation' '400': description: invalid_request content: application/json: schema: type: object properties: error: type: object required: - code - message properties: code: type: string example: invalid_source_input message: type: string required_scope: type: string limit: type: string enum: - per_request - monthly - max_spend - daily required: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD available: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD field: type: string missing: type: array items: type: string expected: type: array items: type: string operations: type: array items: type: string retry_after_ms: type: integer '401': description: invalid_api_key, api_key_expired or api_key_revoked content: application/json: schema: type: object properties: error: type: object required: - code - message properties: code: type: string example: invalid_source_input message: type: string required_scope: type: string limit: type: string enum: - per_request - monthly - max_spend - daily required: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD available: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD field: type: string missing: type: array items: type: string expected: type: array items: type: string operations: type: array items: type: string retry_after_ms: type: integer '402': description: insufficient_balance or spend_limit_exceeded content: application/json: schema: type: object properties: error: type: object required: - code - message properties: code: type: string example: invalid_source_input message: type: string required_scope: type: string limit: type: string enum: - per_request - monthly - max_spend - daily required: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD available: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD field: type: string missing: type: array items: type: string expected: type: array items: type: string operations: type: array items: type: string retry_after_ms: type: integer '403': description: insufficient_scope or organisation_unavailable content: application/json: schema: type: object properties: error: type: object required: - code - message properties: code: type: string example: invalid_source_input message: type: string required_scope: type: string limit: type: string enum: - per_request - monthly - max_spend - daily required: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD available: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD field: type: string missing: type: array items: type: string expected: type: array items: type: string operations: type: array items: type: string retry_after_ms: type: integer '404': description: source_not_found or operation_not_found content: application/json: schema: type: object properties: error: type: object required: - code - message properties: code: type: string example: invalid_source_input message: type: string required_scope: type: string limit: type: string enum: - per_request - monthly - max_spend - daily required: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD available: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD field: type: string missing: type: array items: type: string expected: type: array items: type: string operations: type: array items: type: string retry_after_ms: type: integer '409': description: idempotency_conflict or request_in_progress content: application/json: schema: type: object properties: error: type: object required: - code - message properties: code: type: string example: invalid_source_input message: type: string required_scope: type: string limit: type: string enum: - per_request - monthly - max_spend - daily required: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD available: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD field: type: string missing: type: array items: type: string expected: type: array items: type: string operations: type: array items: type: string retry_after_ms: type: integer '422': description: invalid_source_input content: application/json: schema: type: object properties: error: type: object required: - code - message properties: code: type: string example: invalid_source_input message: type: string required_scope: type: string limit: type: string enum: - per_request - monthly - max_spend - daily required: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD available: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD field: type: string missing: type: array items: type: string expected: type: array items: type: string operations: type: array items: type: string retry_after_ms: type: integer '429': description: rate_limit_exceeded content: application/json: schema: type: object properties: error: type: object required: - code - message properties: code: type: string example: invalid_source_input message: type: string required_scope: type: string limit: type: string enum: - per_request - monthly - max_spend - daily required: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD available: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD field: type: string missing: type: array items: type: string expected: type: array items: type: string operations: type: array items: type: string retry_after_ms: type: integer '502': description: source_error content: application/json: schema: type: object properties: error: type: object required: - code - message properties: code: type: string example: invalid_source_input message: type: string required_scope: type: string limit: type: string enum: - per_request - monthly - max_spend - daily required: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD available: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD field: type: string missing: type: array items: type: string expected: type: array items: type: string operations: type: array items: type: string retry_after_ms: type: integer '503': description: service_unavailable content: application/json: schema: type: object properties: error: type: object required: - code - message properties: code: type: string example: invalid_source_input message: type: string required_scope: type: string limit: type: string enum: - per_request - monthly - max_spend - daily required: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD available: type: object properties: amount: type: number example: 0.023 amount_micro_usd: type: string example: '23000' currency: type: string example: USD field: type: string missing: type: array items: type: string expected: type: array items: type: string operations: type: array items: type: string retry_after_ms: type: integer components: schemas: Continuation: type: object required: - state - actions properties: state: $ref: '#/components/schemas/ContinuationState' actions: type: array minItems: 1 items: type: object required: - action_id - kind - label - requires_authorization - input_schema properties: action_id: type: string format: uuid kind: type: string enum: - select_entity - supply_input label: type: string requires_authorization: type: boolean const: false input_schema: type: object additionalProperties: true ContinuationState: type: object additionalProperties: false description: Signed snapshot returned by this run. Copy unchanged. required: - schema_version - state_ref - revision - expires_at - focus - state_token properties: schema_version: type: string enum: - '2' state_ref: type: string format: uuid revision: type: integer minimum: 0 expires_at: type: string format: date-time focus: type: object additionalProperties: false required: - entity_refs - goal_refs properties: entity_refs: type: array items: type: string format: uuid goal_refs: type: array items: type: string format: uuid state_token: type: string securitySchemes: apiKey: type: http scheme: bearer description: 'An organisation API key: Authorization: Bearer apk_org_live_…' ````