> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vort-sourcing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run status, progress, notices and candidates



## OpenAPI

````yaml /api-reference/openapi.yaml get /runs/{run_id}
openapi: 3.1.0
info:
  title: Vort Partner API
  version: 1.0.0
  summary: Server-to-server API for ATS vendors embedding Vort candidate matching.
  description: >
    Guides: [Integration flow](/integration-flow). UI rules: [UI
    specification](/ui-specification). Notices: [Notices](/notices).


    - Every call is server-to-server. `vpk_` keys and `vot_` org tokens MUST NOT
    reach a browser.

    - Clients MUST ignore unknown response fields; additive changes within v1
    are non-breaking.

    - Notices with an unknown `code` MUST be rendered generically from `title` +
    `body`,
      styled by `severity`, placed by `slot`.
    - Rate limits are per partner (default 120/minute, 20,000/day); `429`
    carries `Retry-After`.

    - Sandbox ([Sandbox guide](/sandbox)): every sandbox response carries
    `x-vort-environment: sandbox`;
      names are masked, reveals are synthetic and free, `target_count` <= 20, 20 real runs
      per organization per 24 h, `cert-*` jobs run certification fixtures, and the
      sandbox-only headers `x-vort-sandbox-simulate` / `x-vort-sandbox-reveal-price` and
      route `POST /sandbox/webhooks/test` exist. None of these exist in production.
  contact:
    name: Vort partner support (always include the run_id)
  license:
    name: Proprietary
    identifier: LicenseRef-Vort-Proprietary
servers:
  - url: https://vort-partner-api.vercel.app/sandbox/v1
    description: Sandbox
security:
  - partnerKey: []
    orgToken: []
tags:
  - name: Activation
    description: Connect a customer organization by redeeming its one-time activation code.
  - name: Users
    description: Register the recruiters who act on runs (a field, never a credential).
  - name: Jobs
    description: Jobs the runs search for.
  - name: Runs
    description: Start runs and read their progress, notices and candidates.
  - name: Candidates
    description: Reveal candidate contact details (charges credits).
  - name: Decisions
    description: Report recruiter decisions and the notices shown (mandatory).
  - name: Sandbox
    description: >-
      Sandbox-only helpers (see the [Sandbox guide](/sandbox)). Not present in
      production (404).
  - name: Webhooks
    description: >-
      Events Vort posts to your registered HTTPS endpoint, signed with
      `x-vort-signature`.
paths:
  /runs/{run_id}:
    get:
      tags:
        - Runs
      summary: Run status, progress, notices and candidates
      operationId: getRun
      parameters:
        - $ref: '#/components/parameters/RunId'
        - $ref: '#/components/parameters/Lang'
      responses:
        '200':
          description: The run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
              example:
                run_id: 9f2b6c1e-3d4a-4e8f-b1c7-0a5d2e9f6b33
                status: running
                progress:
                  confirmed: 7
                  target: 30
                  screened: 184
                notices:
                  - code: location_relaxed
                    severity: warning
                    slot: above_list
                    title: Search widened beyond Tel Aviv
                    body: >-
                      Not enough candidates were found in Tel Aviv, so
                      candidates from outside the area are shown as well.
                  - code: requirement_attribution
                    severity: info
                    slot: on_requirement
                    title: Rejected because of this requirement
                    body: 41 candidates were rejected because of this requirement.
                    ref:
                      requirement_index: 1
                candidates:
                  - id: 48213377
                    name: Yael Cohen
                    title: Staff Backend Engineer
                    company: Northwind Payments
                    location: Ramat Gan, Israel
                    verdict: strong
                    requirements:
                      - index: 0
                        text: 5+ years of backend development in Go or Java
                        kind: must
                        met: true
                        evidence: >-
                          Backend engineer since 2017; Go at Northwind Payments
                          (2021 to present).
                      - index: 1
                        text: Production experience with Kafka
                        kind: must
                        met: true
                        evidence: Led migration of the ledger pipeline to Kafka.
                      - index: 2
                        text: Payments or fintech domain
                        kind: nice
                        met: null
                        evidence: null
                    contact_state: locked
                    reveal_price_credits: 15
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: '`run_not_found` (also for a run of another organization)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    RunId:
      name: run_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    Lang:
      name: x-vort-lang
      in: header
      required: false
      description: Language of notices and messages. Defaults to the partner default.
      schema:
        type: string
        enum:
          - he
          - en
  schemas:
    Run:
      type: object
      required:
        - run_id
        - status
        - progress
        - notices
        - candidates
      properties:
        run_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/RunStatus'
        progress:
          $ref: '#/components/schemas/Progress'
        notices:
          type: array
          items:
            $ref: '#/components/schemas/Notice'
        candidates:
          type: array
          description: Confirmed candidates in Vort's display order.
          items:
            $ref: '#/components/schemas/Candidate'
    Error:
      type: object
      description: >-
        Error envelope. Branch on `error`; unknown codes are handled by HTTP
        status.
      required:
        - error
        - message
      properties:
        error:
          type: string
          examples:
            - invalid_partner_key
            - invalid_org_token
            - partner_disabled
            - organization_disabled
            - rate_limited
            - rate_limit_unavailable
            - code_not_found
            - code_expired
            - external_id_taken
            - invalid_user
            - job_not_found
            - user_not_found
            - run_not_found
            - candidate_not_in_run
            - invalid_decision
        message:
          type: string
      additionalProperties: true
    RunStatus:
      type: string
      description: Treat any other value as `running`.
      examples:
        - running
        - completed
        - failed
    Progress:
      type: object
      required:
        - confirmed
        - target
        - screened
      properties:
        confirmed:
          type: integer
          minimum: 0
        target:
          type: integer
          minimum: 0
        screened:
          type: integer
          minimum: 0
    Notice:
      type: object
      description: >
        Render every notice, including unknown codes, from title + body, styled
        by severity,

        placed by slot. Unknown slot => above_list; unknown severity => warning.
      required:
        - code
        - severity
        - slot
        - title
        - body
      properties:
        code:
          type: string
          description: >-
            Stable identifier; see [Notices](/notices). New codes appear without
            notice.
          examples:
            - requirement_blockers
            - widen_hint
            - already_shown
            - relaxation_ladder
            - location_relaxed
            - global_relaxed
            - paid_fallback
            - lean_search_failed
            - requirement_attribution
            - run_funnel
            - run_progress
            - function_error
        severity:
          type: string
          description: 'Known values: info, warning, blocking.'
          examples:
            - info
            - warning
            - blocking
        slot:
          type: string
          description: 'Known values: above_list, on_candidate, on_requirement, empty_state.'
          examples:
            - above_list
            - on_candidate
            - on_requirement
            - empty_state
        title:
          type: string
        body:
          type: string
        ref:
          type: object
          properties:
            requirement_index:
              type: integer
              minimum: 0
            candidate_id:
              type: integer
              format: int64
    Candidate:
      type: object
      required:
        - id
        - name
        - title
        - company
        - location
        - verdict
        - requirements
        - contact_state
        - reveal_price_credits
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        title:
          type:
            - string
            - 'null'
        company:
          type:
            - string
            - 'null'
        location:
          type:
            - string
            - 'null'
        verdict:
          type: string
          enum:
            - strong
            - good
            - weak
        requirements:
          type: array
          items:
            $ref: '#/components/schemas/CandidateRequirement'
        contact_state:
          type: string
          enum:
            - locked
            - revealed
        reveal_price_credits:
          type: integer
          minimum: 0
          description: Price at the time of this response. Never hard-code.
    CandidateRequirement:
      type: object
      required:
        - index
        - text
        - kind
        - met
        - evidence
      properties:
        index:
          type: integer
          minimum: 0
        text:
          type: string
        kind:
          $ref: '#/components/schemas/RequirementKind'
        met:
          type:
            - boolean
            - 'null'
          description: null = could not be determined from the profile.
        evidence:
          type:
            - string
            - 'null'
    RequirementKind:
      type: string
      enum:
        - must
        - nice
  responses:
    Unauthorized:
      description: '`invalid_partner_key` or `invalid_org_token`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_org_token
            message: The organization token is not valid.
    Forbidden:
      description: '`partner_disabled` or `organization_disabled`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: organization_disabled
            message: This organization's Vort connection is disabled.
    RateLimited:
      description: '`rate_limited`'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limited
            message: Too many requests.
    ServiceUnavailable:
      description: >-
        `rate_limit_unavailable` — the rate limiter could not be checked, so the
        request was refused rather than let through unmetered. Retry with
        backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limit_unavailable
            message: Rate limiting is temporarily unavailable. Retry shortly.
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 0
  securitySchemes:
    partnerKey:
      type: apiKey
      in: header
      name: x-partner-key
      description: 'Partner API key: `vpk_live_` + 48 lowercase hex. Server-side only.'
    orgToken:
      type: apiKey
      in: header
      name: x-vort-org
      description: >-
        Customer org token: `vot_` + 48 lowercase hex, from /activations/redeem.
        Server-side only.

````