> ## Documentation Index > Fetch the complete documentation index at: https://docs.oneperfectslice.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run a slice > Starts an asynchronous AI analysis run for the given slice. Returns `202 Accepted` with a `runId` you can use to poll for results via GET /slice-runs/{id}. Pass an `Idempotency-Key` header to safely retry — same key with same arguments returns the original run, same key with different arguments returns `409`. **Related:** [Get run details](/api-reference/slice-runs/get-run-details) · [Get run evidence](/api-reference/slice-runs/get-run-evidence) · [List runs](/api-reference/slice-runs/list-runs) Runs are asynchronous. After starting a run, poll [Get run details](/api-reference/slice-runs/get-run-details) using the returned `runId`. Check `suggestedPollAfterSeconds` for the recommended wait time between polls. ## OpenAPI ````yaml /api/openapi.yaml post /api/public/v1/slices/{key}/run openapi: 3.1.0 info: title: OnePerfectSlice API version: 1.0.0 description: | Programmatic access to OnePerfectSlice. Authenticate with a team-scoped API key (Bearer sk_...) obtained from Org Settings → API Keys. servers: - url: https://app.oneperfectslice.ai description: Production security: - bearerAuth: [] paths: /api/public/v1/slices/{key}/run: post: tags: - Slices summary: Run a slice description: > Starts an asynchronous AI analysis run for the given slice. Returns `202 Accepted` with a `runId` you can use to poll for results via GET /slice-runs/{id}. Pass an `Idempotency-Key` header to safely retry — same key with same arguments returns the original run, same key with different arguments returns `409`. **Related:** [Get run details](/api-reference/slice-runs/get-run-details) · [Get run evidence](/api-reference/slice-runs/get-run-evidence) · [List runs](/api-reference/slice-runs/list-runs) operationId: runSlice parameters: - name: key in: path required: true schema: type: string description: Unique slice key - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Client-provided idempotency key (Stripe convention). Same key + same args returns original runId. Same key + different args returns 409. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunSliceRequest' responses: '202': description: Run accepted (async execution started) content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/RunCreatedResponse' '400': description: Invalid filters or idempotency key content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: invalidFilters: value: error: code: INVALID_FILTERS message: Filter validation failed invalidIdempotencyKey: value: error: code: INVALID_IDEMPOTENCY_KEY message: Idempotency key must be between 1 and 255 characters '401': $ref: '#/components/responses/Unauthorized' '404': description: Slice not found content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: SLICE_NOT_FOUND message: Slice not found '409': description: Idempotency key conflict (same key, different args) content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: IDEMPOTENCY_KEY_CONFLICT message: Idempotency key was already used with different arguments '429': description: Team already has the maximum number of active slice runs content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: CONCURRENT_RUN_LIMIT message: >- Maximum of 5 concurrent slice runs per team. Wait for existing runs to complete. '503': description: Temporary unavailability during billing or idempotency admission content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: billingUnavailable: value: error: code: BILLING_UNAVAILABLE message: Usage gating is temporarily unavailable idempotencyInProgress: value: error: code: IDEMPOTENCY_KEY_IN_PROGRESS message: >- A run for this Idempotency-Key is currently being created. Retry after a short delay. security: - bearerAuth: [] components: schemas: RunSliceRequest: type: object description: >- Filters and options for starting a slice run. All fields are optional — omit filters to analyze all recent calls. properties: dateFrom: type: string format: date-time description: Start datetime (ISO-8601) example: '2026-03-26T00:00:00Z' dateTo: type: string format: date-time description: End datetime (ISO-8601) example: '2026-04-26T00:00:00Z' callTypes: type: array items: type: string maxItems: 100 description: Filter by call types sourceIds: type: array items: type: string maxItems: 100 description: Filter by source file IDs userPrompt: type: string description: Optional user prompt to customize analysis callOwnerEmails: type: array items: type: string maxItems: 100 description: Filter by call owner emails companyDomains: type: array items: type: string maxItems: 100 description: Filter by company domains crmDealIds: type: array items: type: integer format: int64 maxItems: 100 description: Filter by CRM deal IDs crmCompanyIds: type: array items: type: integer format: int64 maxItems: 100 description: Filter by CRM company IDs crmDealStages: type: array items: type: string maxItems: 100 description: Filter by CRM deal stages example: - Qualification - Proposal crmAmountMin: type: number description: Minimum CRM deal amount crmAmountMax: type: number description: Maximum CRM deal amount crmCustomFieldFilters: type: array items: $ref: '#/components/schemas/CrmFieldFilterValue' description: Custom CRM field filters RunCreatedResponse: type: object required: - runId - sliceKey - sliceTitle - status properties: runId: type: integer format: int64 description: Unique run identifier for polling example: 12345 sliceKey: type: string example: high_intent_deals sliceTitle: type: string example: High-Intent Deals status: type: string enum: - running description: Always "running" for a newly created run example: running ApiError: type: object description: Standard error envelope for all public API error responses required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable UPPER_SNAKE_CASE error code example: INVALID_TOKEN message: type: string description: Human-readable error description example: Token is invalid details: type: object description: Optional additional error context additionalProperties: true CrmFieldFilterValue: type: object description: Custom CRM field filter required: - entityType - fieldName - fieldType properties: entityType: type: string enum: - deal - company - contact description: CRM entity type fieldName: type: string description: Field name in the CRM fieldType: type: string enum: - string - number - date - datetime - boolean - enumeration description: Data type of the field stringValue: type: string description: Filter value for string fields numberMin: type: number description: Range start for number fields numberMax: type: number description: Range end for number fields dateStart: type: string description: Range start for date/datetime fields (ISO-8601) dateEnd: type: string description: Range end for date/datetime fields (ISO-8601) booleanValue: type: boolean description: Filter value for boolean fields enumValues: type: array items: type: string description: Selected values for enumeration fields (multi-select) responses: Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: missingToken: value: error: code: MISSING_TOKEN message: Authorization header with Bearer token is required invalidToken: value: error: code: INVALID_TOKEN message: Token is invalid tokenRevoked: value: error: code: TOKEN_REVOKED message: Token has been revoked tokenExpired: value: error: code: TOKEN_EXPIRED message: Token has expired securitySchemes: bearerAuth: type: http scheme: bearer description: API key with sk_ prefix. Create one in Org Settings → API Keys. x-default: sk_your_api_key ````