---
title: "Start an analysis"
method: POST
path: "/api/v1/analyses"
tags: ["Analyses"]
---

# Start an analysis

`POST /api/v1/analyses`

## Request

- Base URL: `https://app.probbai.com`
- URL: `https://app.probbai.com/api/v1/analyses`
- Auth: HTTP bearer

Submit the uploaded resume for asynchronous analysis against its job description. Use this after a successful storage upload and a current quote.

## Before you call

Send the prepared reportId, quoteFingerprint, and a stable Idempotency-Key. Capacity and the workspace allowance are checked at admission.

**Required scope:** `analyses:write`.

## What happens next

A 202 means the analysis was accepted, not completed. Save attemptId and follow statusUrl or report events. The accepted file is frozen for this attempt.

## Recovery

Retry identical requests after timeouts. QUOTE_STALE needs a new quote/key. INVALID_UPLOAD needs a corrected upload. ACTIVE_ANALYSIS_LIMIT means wait for capacity. After terminal failure, a deliberate new attempt needs a new key/current quote; completed analyses cannot be restarted here.

[Follow the complete workflow](/integration-api/) · [Errors and retries](/api-errors/)

## Headers

- `Idempotency-Key` string, required

## Request body

- AnalysisInput
  - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
  - `quoteFingerprint` string, required: Fingerprint copied unchanged from the corresponding current quote. Changing quote inputs requires a new quote.

## Response `202`

A 202 means the analysis was accepted, not completed. Save attemptId and follow statusUrl or report events. The accepted file is frozen for this attempt.

- object
  - `data` Admission, required
    - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
    - `attemptId` string, required: Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available.
    - `statusUrl` string, required: Relative API path to poll with the same workspace API key. Resolve against your application origin.

## Other responses

- `400`: Invalid input or cursor
- `401`: Invalid, expired, or revoked API key
- `403`: Disabled organisation or missing scope
- `404`: The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.
- `405`: Method not allowed; consult Allow for supported methods
- `409`: Retry identical requests after timeouts. QUOTE_STALE needs a new quote/key. INVALID_UPLOAD needs a corrected upload. ACTIVE_ANALYSIS_LIMIT means wait for capacity. After terminal failure, a deliberate new attempt needs a new key/current quote; completed analyses cannot be restarted here.
- `422`: Input cannot be processed or workspace allowance/capacity is insufficient. Inspect error.reason before retrying.
- `429`: Request limit exceeded
- `500`: Unexpected failure
- `503`: Service unavailable

---

[API](https://skmtc.dev/probbai/apis/probb-ai-customer-api.md) · [All operations](https://skmtc.dev/probbai/apis/probb-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/probbai/apis/probb-ai-customer-api/revisions/33a3294530e4?raw)