> ## Documentation Index > Fetch the complete documentation index at: https://docs.useasterisk.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Document only operations in the linked OpenAPI contract: the source-data ingestion operations and the source-scoped outbound webhook management operations. > Treat the generated OpenAPI document as authoritative for request fields. Never invent compatibility fields, alternate endpoints, or additional source models. > Preserve explicit nulls, decimal strings, timestamps, source identifiers, immutable version identifiers, and document-version links exactly as defined. # List a customer's KYB runs (by external ID) > Lists KYB runs for the customer addressed by your source's customer externalId, newest first. Pass nextCursor as cursor to read the next page. Status is derived from the run and its Case: pending (queued), running, needs_review (finished with open issues for an analyst), completed (finished without open issues), or failed. Only customers owned by the calling ingestion source are visible. ## OpenAPI ````yaml /openapi/ingestion.openapi.yaml get /api/ingestion/customers/by-external-id/{externalId}/kyb-runs openapi: 3.1.0 info: title: Karsa Data Ingestion API version: current description: >- Source-bound writes for documents, business onboardings, customers, kyb-dossiers, accounts, transactions, outcomes, screening observations, screening dispositions, monitoring controls, monitoring control executions, historical RFI events, source checkpoints, native SEON screening observations, native AiPrise screening observations, and native Chainalysis screening observations. servers: - url: https://api.sandbox.useasterisk.com description: Karsa sandbox API (synthetic test data) - url: https://api.useasterisk.com description: Karsa production API security: [] tags: - name: Customers description: >- Create and version individual or business customer records, including atomic business onboarding where every beneficial owner is an individual Customer. - name: Verifications description: >- Submit immutable customer evidence snapshots for KYC or KYB evaluation, or start a KYB run for a business customer and poll its status. - name: Accounts description: >- Create and version customer-linked bank accounts, virtual accounts, and wallets without coupling the contract to a provider. - name: Documents description: Submit immutable document bytes or URL references and metadata. - name: Transactions description: Create and version money-movement records. - name: Sources description: >- Record source-attested, append-only completeness checkpoints used to qualify downstream evidence windows. - name: Outcomes description: >- Record source outcomes against customers, accounts, transactions, or documents. - name: Screening description: >- Submit provider-neutral verification, screening, alert, and reviewer-disposition evidence for Routine 6 qualification. - name: Controls description: >- Submit the source-owned monitoring control catalog and immutable execution evidence used to assess control coverage. - name: Requests description: >- Submit immutable historical request-for-information lifecycle events used to measure repeat requests and expiry. - name: Webhooks description: >- Manage source-scoped outbound destinations, receive later KYB evaluation lifecycle changes, and list recorded events to catch up on missed deliveries. paths: /api/ingestion/customers/by-external-id/{externalId}/kyb-runs: get: tags: - Verifications summary: List a customer's KYB runs (by external ID) description: >- Lists KYB runs for the customer addressed by your source's customer externalId, newest first. Pass nextCursor as cursor to read the next page. Status is derived from the run and its Case: pending (queued), running, needs_review (finished with open issues for an analyst), completed (finished without open issues), or failed. Only customers owned by the calling ingestion source are visible. operationId: listKybRunsByExternalId parameters: - schema: type: string minLength: 1 description: The customer externalId your ingestion source supplied required: true name: externalId in: path - schema: type: integer minimum: 1 maximum: 100 default: 20 required: false name: limit in: query - schema: type: string minLength: 1 maxLength: 200 required: false name: cursor in: query responses: '200': description: One page of KYB runs content: application/json: schema: $ref: '#/components/schemas/KybRunList' examples: page: value: items: - id: workflow_run_example_01 status: needs_review customerId: customer_resource_example_01 externalCustomerId: business-example-001 caseId: case_example_01 createdAt: '2026-09-25T12:00:00.000Z' startedAt: '2026-09-25T12:00:02.000Z' completedAt: '2026-09-25T12:02:10.000Z' result: outcome: ATTENTION_REQUIRED openIssueCount: 2 caseId: case_example_01 failure: null nextCursor: null '400': description: 'INVALID_REQUEST: The request did not match the ingestion schema' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: INVALID_REQUEST: value: type: https://karsa.app/problems/invalid-request title: Ingestion Rejected status: 400 detail: The request did not match the ingestion schema code: INVALID_REQUEST requestId: req_example_01 '401': description: >- AUTHENTICATION_REQUIRED: A source-bound bearer credential is required content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: AUTHENTICATION_REQUIRED: value: type: https://karsa.app/problems/authentication-required title: Ingestion Rejected status: 401 detail: A source-bound bearer credential is required code: AUTHENTICATION_REQUIRED requestId: req_example_01 '403': description: >- MACHINE_PRINCIPAL_REQUIRED: A source-bound machine principal is required TENANT_NOT_ACTIVE: The workspace is not active content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: MACHINE_PRINCIPAL_REQUIRED: value: type: https://karsa.app/problems/machine-principal-required title: Ingestion Rejected status: 403 detail: A source-bound machine principal is required code: MACHINE_PRINCIPAL_REQUIRED requestId: req_example_01 TENANT_NOT_ACTIVE: value: type: https://karsa.app/problems/tenant-not-active title: Ingestion Rejected status: 403 detail: The workspace is not active code: TENANT_NOT_ACTIVE requestId: req_example_01 '404': description: 'CUSTOMER_NOT_FOUND: The customer was not found' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: CUSTOMER_NOT_FOUND: value: type: https://karsa.app/problems/customer-not-found title: Ingestion Rejected status: 404 detail: The customer was not found code: CUSTOMER_NOT_FOUND requestId: req_example_01 '429': description: 'RATE_LIMITED: The ingestion source exceeded its configured rate' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: RATE_LIMITED: value: type: https://karsa.app/problems/rate-limited title: Ingestion Rejected status: 429 detail: The ingestion source exceeded its configured rate code: RATE_LIMITED requestId: req_example_01 '500': description: >- INGESTION_INTERNAL_ERROR: The ingestion request could not be completed content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: INGESTION_INTERNAL_ERROR: value: type: https://karsa.app/problems/ingestion-internal-error title: Ingestion Unavailable status: 500 detail: The ingestion request could not be completed code: INGESTION_INTERNAL_ERROR requestId: req_example_01 security: - ingestionBearer: [] components: schemas: KybRunList: type: object properties: items: type: array items: type: object properties: id: type: string minLength: 1 status: anyOf: - type: string enum: - pending - running - needs_review - completed - failed - type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,119}$ customerId: type: string minLength: 1 externalCustomerId: type: - string - 'null' minLength: 1 caseId: type: string minLength: 1 createdAt: type: string format: date-time startedAt: type: - string - 'null' format: date-time completedAt: type: - string - 'null' format: date-time result: type: - object - 'null' properties: outcome: anyOf: - type: string enum: - ATTENTION_REQUIRED - NO_ATTENTION - APPROVED - REVIEW_REQUIRED - RFI_REQUIRED - RESEARCH_REQUIRED - HUMAN_REVIEW_REQUIRED - type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,119}$ openIssueCount: type: integer minimum: 0 caseId: type: string minLength: 1 required: - outcome - openIssueCount - caseId additionalProperties: false failure: type: - object - 'null' properties: code: type: string minLength: 1 required: - code additionalProperties: false required: - id - status - customerId - externalCustomerId - caseId - createdAt - startedAt - completedAt - result - failure additionalProperties: false nextCursor: type: - string - 'null' minLength: 1 required: - items - nextCursor additionalProperties: false Problem: type: object properties: type: type: string minLength: 1 title: type: string minLength: 1 status: type: integer detail: type: string minLength: 1 code: type: string minLength: 1 requestId: type: string minLength: 1 existingRunId: type: string minLength: 1 issues: type: array items: type: object properties: path: type: string message: type: string required: - path - message additionalProperties: false maxItems: 20 required: - type - title - status - detail - code - requestId additionalProperties: false securitySchemes: ingestionBearer: type: http scheme: bearer description: >- Source-bound WorkOS API key or configured machine OIDC token. OIDC webhook management requires karsa:webhooks:manage. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.