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

# Check if results exist for a screen

> Returns whether results have been generated for a screen. If the
screen should have results (status `ss_completed` or `ss_closed`
with `complete_state = finished`) but doesn't, automatically
triggers asynchronous background generation.

**Read-only** (except for the background trigger side effect).

Registered as `wp_ajax_sagescreen_check_results` — **login required**.




## OpenAPI

````yaml /openapi/private/specs/wp/screen.yml post /wp-admin/admin-ajax.php?action=sagescreen_check_results
openapi: 3.1.0
info:
  title: SageScreen — Screen Module
  description: |
    Screen (interview) lifecycle management. A screen represents a single
    candidate screening session — from invite creation through completion,
    results generation, and PDF download.

    **CPT:** `ss_screen`
    **Custom statuses:** `ss_draft`, `ss_invited`, `ss_accepted`, `ss_started`,
    `ss_completed`, `ss_closed`, `ss_cancelled`, `ss_expired`

    Screens are created when candidates are invited to a sage, progress through
    the interview, and conclude with AI-generated results including category
    scores, a summary, recommendation, and a hire/no-hire determination.
  version: 1.0.0
servers:
  - url: https://{domain}/wp-json/sagescreen/v1
    description: WordPress REST API
    variables:
      domain:
        default: api.sagescreen.app
security: []
tags:
  - name: Screen – Testing
    description: Test invite and temperature check endpoints
  - name: Screen – Results
    description: Results generation, checking, regeneration, feedback, and download
  - name: Screen – Workflow
    description: Workflow progression (skip testing)
paths:
  /wp-admin/admin-ajax.php?action=sagescreen_check_results:
    post:
      tags:
        - Screen – Results
      summary: Check if results exist for a screen
      description: |
        Returns whether results have been generated for a screen. If the
        screen should have results (status `ss_completed` or `ss_closed`
        with `complete_state = finished`) but doesn't, automatically
        triggers asynchronous background generation.

        **Read-only** (except for the background trigger side effect).

        Registered as `wp_ajax_sagescreen_check_results` — **login required**.
      operationId: ajaxCheckResults
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CheckResultsRequest'
      responses:
        '200':
          description: Results check result
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CheckResultsSuccess'
                  - $ref: '#/components/schemas/AjaxErrorResponse'
              examples:
                hasResults:
                  summary: Results exist
                  value:
                    success: true
                    data:
                      has_results: true
                noResultsNotExpected:
                  summary: No results and screen not in finished state
                  value:
                    success: true
                    data:
                      has_results: false
                      should_have_results: false
                triggered:
                  summary: No results but generation triggered in background
                  value:
                    success: true
                    data:
                      has_results: false
                      should_have_results: true
                      triggered: true
      security:
        - wpAjaxNonce: []
components:
  schemas:
    CheckResultsRequest:
      type: object
      required:
        - action
        - nonce
        - screen_id
      properties:
        action:
          type: string
          const: sagescreen_check_results
        nonce:
          type: string
          description: WP nonce for `sagescreen_frontend_nonce`
          examples:
            - abc123def456
        screen_id:
          type: integer
          description: Post ID of the `ss_screen`
          examples:
            - 5678
    CheckResultsSuccess:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
            - has_results
          properties:
            has_results:
              type: boolean
              description: Whether results have been generated
              examples:
                - true
            should_have_results:
              type: boolean
              description: >
                Present when `has_results` is false. True if screen is in

                a state where results should exist (completed/closed +
                finished).
              examples:
                - false
            triggered:
              type: boolean
              description: |
                Present when `should_have_results` is true. Indicates that
                asynchronous background generation was spawned.
              examples:
                - true
    AjaxErrorResponse:
      type: object
      description: |
        Standard AJAX error. The `data` field is either a plain string
        or an object with a `message` field.
      properties:
        success:
          type: boolean
          const: false
        data:
          oneOf:
            - type: string
              description: Error message as plain string
              examples:
                - Security check failed
            - type: object
              properties:
                message:
                  type: string
                  examples:
                    - Screen ID is required
        message:
          type: string
          description: |
            Present on some endpoints that use `wp_send_json()` directly
            instead of `wp_send_json_error()`.
          examples:
            - Security check failed
  securitySchemes:
    wpAjaxNonce:
      type: apiKey
      in: query
      name: nonce
      description: WordPress AJAX nonce (passed as form field, verified per-action)

````