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

# Get a scan result

> Returns the result for one uploaded file or social media URL. The
`requestId` comes from the `POST /api/files/aws-presigned` or
`POST /api/files/social` response, or from the URL of the result in the
web app. Poll this endpoint until `overallStatus` is no longer
`ANALYZING` or `DOWNLOADING`.

Rely on the ensemble result (`overallStatus` and `resultsSummary`)
rather than on individual `models[]` results.

### Score interpretation

When a score is present, it maps to one of three conclusions. The same
bands apply to the overall score (`resultsSummary.metadata.finalScore`)
and to each model's `finalScore`.

| Conclusion | Score | API status | Guidance |
| --- | --- | --- | --- |
| Authentic | 1–44 | `AUTHENTIC` | Low likelihood of manipulation or AI generation; continue normal workflows |
| Suspicious | 45–55 | `SUSPICIOUS` | Moderate likelihood of manipulation; worth a closer look or human review |
| Manipulated | 56–99 | `FAKE` | High likelihood that the content has been manipulated or AI-generated; trigger escalation or secondary validation |

The status comes from the ensemble's decision, and the context model
can override it. The bands describe how the scores line up; they are
not a rule the API applies separately.

Scores are always > 0 and < 100. A higher score means a higher
likelihood of manipulation; it does not mean the entire file is
synthetic, or that every frame, second or pixel was generated. When
the context model sets the conclusion, `finalScore` may be null; use
`overallStatus`.

### NOT_APPLICABLE and UNABLE_TO_EVALUATE

`NOT_APPLICABLE` means the media has characteristics known to affect
accuracy. The reasons are listed in `resultsSummary.metadata.reasons`.

- Image: for example `relevance: no faces detected/faces too small`,
  `size: face too small`, `quality: face too blurry`
- Audio: for example `duration: audio too short (<1.5s)`,
  `duration: silence removed audio too short (<1.5s)`,
  `loudness: audio too quiet`, dialtone and/or music
  (`detected: ...`), `cross-talk: more than one speaker detected`,
  `quality: audio too noisy`, `language`
- Video: reasons may be empty (for example `duration: video too long`);
  use `modelMetadataUrl` for timeline and scene detail.

`UNABLE_TO_EVALUATE` means an error occurred while processing the file,
for example a model timeout or failure. The error is described in
`resultsSummary.error`.

### Visualization artifacts

`aggregationResultUrl` is the storage key of the scan's
`aggregation.json`, shaped like
`{organizationId}/{requestId}/aggregation.json` (older scans may use a
legacy layout); it is not a downloadable URL. `modelMetadataUrl` is the pre-signed URL of that same
file, and for combined video and audio scans `audioModelMetadataUrl`
points at the extracted-audio aggregation JSON. The Reality Defender UI
loads this JSON to render report detail. Approximate contents:

- Image: `bboxes`, `conclusions`, optional `contextResult`
- Video: frame and timeline fields (scenes, frames, tubes), `models`,
  `ensembles`, `conclusions`, optional `contextResult`
- Audio: `chunks`, `languages`, `conclusions`, `models`, `ensembles`,
  plus audio metadata
- Text: `models`, `ensembles`, `conclusions`

From a client, download `modelMetadataUrl` / `audioModelMetadataUrl`,
not `aggregationResultUrl`.

### Pre-signed URL expiry

`heatmaps`, `thumbnail`, `storageLocation`, `modelMetadataUrl`,
`audioModelMetadataUrl` and `explainabilityUrl` are pre-signed URLs
that expire after 15 minutes (`X-Amz-Expires=900`). Call this endpoint
again for the same `requestId` to get fresh URLs.

### Models

Model names are not a stable contract: detectors can be added, renamed
or removed. Always read `models[].name` from the response rather than
hard-coding slugs. Illustrative examples:

- Image: `rd-cedar-img`, `rd-elm-img`, `rd-oak-img`, `rd-pine-img`,
  `rd-img-ensemble`, `rd-context-img`
- Video: `rd-erie-vid`, `rd-tahoe-vid`, `rd-dynamics-vid`,
  `rd-vid-ensemble`, `rd-context-vid`
- Audio: `rd-slim-aud`, `rd-everest-aud`, `rd-aud-ensemble`
- Text: `rd-llm-txt`

The set reflects the detectors live at upload time; a context model
reports NOT_APPLICABLE when context models are disabled for the
organization.



## OpenAPI

````yaml /openapi/realscan.json get /api/media/users/{requestId}
openapi: 3.1.1
info:
  title: Reality Defender RealScan API
  description: |-
    > **Note:** Reality Defender recommends the
    > [Reality Defender SDKs](/sdks/quickstart) (Python, TypeScript, Go, Java
    > and Rust) for most integrations.

    ## Authentication

    Every request except `PUT /api/files/{requestId}` (authorized by its
    `token`) and `GET /api/health` must send your API key in the `X-API-KEY`
    header (header names are case-insensitive). Create a key on the Reality
    Defender web platform under
    [API keys](https://app.realitydefender.ai/api-keys).

    API keys are linked to a user. Organization owners, admins and viewers
    can view uploads from all users in the organization; contributors see
    only their own.

    ## Workflow

    1. Request a signed upload URL with `POST /api/files/aws-presigned`.
    2. `PUT` the file to the returned `signedUrl`. Alternatively, skip both
       steps and submit a social media URL with `POST /api/files/social`.
    3. Poll `GET /api/media/users/{requestId}` until the scan reaches a final
       status, or set up a webhook. Analysis time varies with file size and
       type.

    ## Interpreting results

    Focus on the ensemble result (`overallStatus` and `resultsSummary`) rather
    than on individual model results.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.prd.realitydefender.xyz
security:
  - apiKey: []
tags:
  - name: RealScan
    description: >-
      Deepfake detection for uploaded files and social media links: upload, scan
      status and results, usage, and feedback.
paths:
  /api/media/users/{requestId}:
    get:
      tags:
        - RealScan
      summary: Get a scan result
      description: >-
        Returns the result for one uploaded file or social media URL. The

        `requestId` comes from the `POST /api/files/aws-presigned` or

        `POST /api/files/social` response, or from the URL of the result in the

        web app. Poll this endpoint until `overallStatus` is no longer

        `ANALYZING` or `DOWNLOADING`.


        Rely on the ensemble result (`overallStatus` and `resultsSummary`)

        rather than on individual `models[]` results.


        ### Score interpretation


        When a score is present, it maps to one of three conclusions. The same

        bands apply to the overall score (`resultsSummary.metadata.finalScore`)

        and to each model's `finalScore`.


        | Conclusion | Score | API status | Guidance |

        | --- | --- | --- | --- |

        | Authentic | 1–44 | `AUTHENTIC` | Low likelihood of manipulation or AI
        generation; continue normal workflows |

        | Suspicious | 45–55 | `SUSPICIOUS` | Moderate likelihood of
        manipulation; worth a closer look or human review |

        | Manipulated | 56–99 | `FAKE` | High likelihood that the content has
        been manipulated or AI-generated; trigger escalation or secondary
        validation |


        The status comes from the ensemble's decision, and the context model

        can override it. The bands describe how the scores line up; they are

        not a rule the API applies separately.


        Scores are always > 0 and < 100. A higher score means a higher

        likelihood of manipulation; it does not mean the entire file is

        synthetic, or that every frame, second or pixel was generated. When

        the context model sets the conclusion, `finalScore` may be null; use

        `overallStatus`.


        ### NOT_APPLICABLE and UNABLE_TO_EVALUATE


        `NOT_APPLICABLE` means the media has characteristics known to affect

        accuracy. The reasons are listed in `resultsSummary.metadata.reasons`.


        - Image: for example `relevance: no faces detected/faces too small`,
          `size: face too small`, `quality: face too blurry`
        - Audio: for example `duration: audio too short (<1.5s)`,
          `duration: silence removed audio too short (<1.5s)`,
          `loudness: audio too quiet`, dialtone and/or music
          (`detected: ...`), `cross-talk: more than one speaker detected`,
          `quality: audio too noisy`, `language`
        - Video: reasons may be empty (for example `duration: video too long`);
          use `modelMetadataUrl` for timeline and scene detail.

        `UNABLE_TO_EVALUATE` means an error occurred while processing the file,

        for example a model timeout or failure. The error is described in

        `resultsSummary.error`.


        ### Visualization artifacts


        `aggregationResultUrl` is the storage key of the scan's

        `aggregation.json`, shaped like

        `{organizationId}/{requestId}/aggregation.json` (older scans may use a

        legacy layout); it is not a downloadable URL. `modelMetadataUrl` is the
        pre-signed URL of that same

        file, and for combined video and audio scans `audioModelMetadataUrl`

        points at the extracted-audio aggregation JSON. The Reality Defender UI

        loads this JSON to render report detail. Approximate contents:


        - Image: `bboxes`, `conclusions`, optional `contextResult`

        - Video: frame and timeline fields (scenes, frames, tubes), `models`,
          `ensembles`, `conclusions`, optional `contextResult`
        - Audio: `chunks`, `languages`, `conclusions`, `models`, `ensembles`,
          plus audio metadata
        - Text: `models`, `ensembles`, `conclusions`


        From a client, download `modelMetadataUrl` / `audioModelMetadataUrl`,

        not `aggregationResultUrl`.


        ### Pre-signed URL expiry


        `heatmaps`, `thumbnail`, `storageLocation`, `modelMetadataUrl`,

        `audioModelMetadataUrl` and `explainabilityUrl` are pre-signed URLs

        that expire after 15 minutes (`X-Amz-Expires=900`). Call this endpoint

        again for the same `requestId` to get fresh URLs.


        ### Models


        Model names are not a stable contract: detectors can be added, renamed

        or removed. Always read `models[].name` from the response rather than

        hard-coding slugs. Illustrative examples:


        - Image: `rd-cedar-img`, `rd-elm-img`, `rd-oak-img`, `rd-pine-img`,
          `rd-img-ensemble`, `rd-context-img`
        - Video: `rd-erie-vid`, `rd-tahoe-vid`, `rd-dynamics-vid`,
          `rd-vid-ensemble`, `rd-context-vid`
        - Audio: `rd-slim-aud`, `rd-everest-aud`, `rd-aud-ensemble`

        - Text: `rd-llm-txt`


        The set reflects the detectors live at upload time; a context model

        reports NOT_APPLICABLE when context models are disabled for the

        organization.
      operationId: getMediaDetail
      parameters:
        - name: requestId
          required: true
          in: path
          description: Request ID of the upload or social media submission.
          schema:
            type: string
      responses:
        '200':
          description: The scan result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaItem'
              examples:
                authentic:
                  summary: Authentic video with audio analysis
                  value:
                    filename: your_file_1736942400000.mp4
                    originalFileName: your-file.mp4
                    requestId: 8b0d4c1e-2f3a-4b5c-8d6e-7f8a9b0c1d2e
                    uploadedDate: '2025-01-15T12:00:00.000Z'
                    mediaType: VIDEO
                    showAudioResult: true
                    audioRequestId: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                    userId: user_0123456789abcdef
                    institutionId: 3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b
                    releaseVersion: 2.3.1
                    overallStatus: AUTHENTIC
                    resultsSummary:
                      status: AUTHENTIC
                      metadata:
                        finalScore: 12
                    models:
                      - name: rd-vid-ensemble
                        data:
                          score: 0.12
                          decision: AUTHENTIC
                          raw_score: 0.12
                        status: AUTHENTIC
                        predictionNumber: 0.12
                        normalizedPredictionNumber: 12
                        rollingAvgNumber: null
                        finalScore: 12
                    storageLocation: >-
                      https://<bucket>.s3.amazonaws.com/<key>?X-Amz-Expires=900&...
                    thumbnail: >-
                      https://<bucket>.s3.amazonaws.com/<key>/thumbnail.png?X-Amz-Expires=900&...
                    aggregationResultUrl: >-
                      3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b/8b0d4c1e-2f3a-4b5c-8d6e-7f8a9b0c1d2e/aggregation.json
                    modelMetadataUrl: >-
                      https://<bucket>.s3.amazonaws.com/<key>/aggregation.json?X-Amz-Expires=900&...
                    audioModelMetadataUrl: >-
                      https://<bucket>.s3.amazonaws.com/<audio-key>/aggregation.json?X-Amz-Expires=900&...
                    heatmaps:
                      rd-vid-ensemble: >-
                        https://<bucket>.s3.amazonaws.com/<key>/heatmaps/rd-vid-ensemble/heatmap.png?X-Amz-Expires=900&...
                    explainabilityUrl: ''
                notApplicable:
                  summary: Image with no usable faces
                  value:
                    requestId: 8b0d4c1e-2f3a-4b5c-8d6e-7f8a9b0c1d2e
                    mediaType: IMAGE
                    overallStatus: NOT_APPLICABLE
                    resultsSummary:
                      status: NOT_APPLICABLE
                      metadata:
                        reasons:
                          - code: 'relevance: no faces detected/faces too small'
                            type: Not applicable
                            name: No faces detected / Faces too small
                            explanation: >-
                              The media was rejected during pre-processing. No
                              faces were detected or faces were too small for
                              analysis.
                            rawReason: 'relevance: no faces detected/faces too small'
                unableToEvaluate:
                  summary: Processing error
                  value:
                    requestId: 8b0d4c1e-2f3a-4b5c-8d6e-7f8a9b0c1d2e
                    mediaType: IMAGE
                    overallStatus: UNABLE_TO_EVALUATE
                    resultsSummary:
                      status: UNABLE_TO_EVALUATE
                      metadata: {}
                      error:
                        code: model-error
                        type: Processing error
                        name: Analysis failed
                        explanation: >-
                          Our models experienced a technical failure. Please try
                          again.
        '404':
          description: Media not found, or not visible to the caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseError'
components:
  schemas:
    MediaItem:
      type: object
      properties:
        requestId:
          type: string
          description: ID used to fetch this result.
        name:
          type: string
          description: >-
            Storage key of the uploaded media object. Use `scanName` for
            display.
        scanName:
          type: string
          description: Name given to the scan.
        filename:
          type: string
          description: Display / upload file name.
        originalFileName:
          type: string
          description: Original uploaded file name.
        mediaType:
          type: string
          description: '`IMAGE`, `VIDEO`, `AUDIO` or `TEXT`.'
        overallStatus:
          $ref: '#/components/schemas/ScanStatus'
        origin:
          type: string
          description: API key name (or redacted key), `Social link`, or `Uploaded`.
        socialLink:
          type: string
          description: >-
            Social media URL. Always present; meaningful only for social media
            submissions.
        socialLinkDownloaded:
          type: boolean
          description: >-
            Whether the social media URL was downloaded. Always present;
            meaningful only for social media submissions.
        socialLinkDownloadFailed:
          type: boolean
          description: >-
            Whether downloading the social media URL failed. Always present;
            meaningful only for social media submissions.
        showAudioResult:
          type: boolean
          description: >-
            For video scans, whether the extracted-audio result is included in
            this result. Set at upload from the request or the organization's
            auto audio analysis setting, or later when audio analysis is
            requested. Usually `false` for non-video media.
        audioRequestId:
          type: string
          nullable: true
          description: >-
            Request ID of the extracted-audio scan, set for every video scan;
            `''` or null otherwise.
        thumbnail:
          type: string
          description: Pre-signed thumbnail URL, or `""` when unavailable.
        userId:
          type: string
          description: ID of the uploading user.
        institutionId:
          type: string
          nullable: true
          description: Organization ID.
        releaseVersion:
          type: string
          description: Platform release version used for the scan; defaults to `1.0.0`.
        uploadedDate:
          type: string
          description: Upload timestamp (ISO 8601).
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp.
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp.
        resultsSummary:
          type: object
          nullable: true
          description: Ensemble status, score, and optional reasons or error.
          properties:
            status:
              $ref: '#/components/schemas/ScanStatus'
            metadata:
              type: object
              properties:
                finalScore:
                  type: number
                  nullable: true
                  description: >-
                    Overall score, when present; always > 0 and < 100. Authentic
                    1–44, Suspicious 45–55, Manipulated 56–99. When the context
                    model sets the conclusion, `finalScore` may be null; use
                    `overallStatus`.
                languages:
                  type: array
                  description: Detected languages, for audio.
                  items:
                    type: string
                reasons:
                  type: array
                  description: Why the result is `NOT_APPLICABLE`.
                  items:
                    $ref: '#/components/schemas/ScanReason'
            error:
              type: object
              description: >-
                Why the scan failed, when the status is `UNABLE_TO_EVALUATE` or
                `DOWNLOAD_FAILED`.
              properties:
                code:
                  type: string
                  description: Stable machine-readable code, for example `model-error`.
                type:
                  type: string
                  description: >-
                    Category of the error: `Import error`, `Not applicable`,
                    `Processing error`, `System error` or `Download failed`.
                name:
                  type: string
                  description: Short human-readable title.
                explanation:
                  type: string
                  description: User-facing explanation.
          required:
            - status
            - metadata
        models:
          type: array
          description: >-
            Per-model detection results. Missing or in-flight models may appear
            with `status: ANALYZING` and null scores. Models that do not apply
            to the media type typically return `status: NOT_APPLICABLE` with
            `code: not_applicable` and `data: null`.
          items:
            type: object
            properties:
              name:
                type: string
                description: >-
                  Model slug. Model names can change as detectors are added,
                  renamed or retired.
              status:
                type: string
                description: >-
                  Model status, for example `FAKE`, `AUTHENTIC`, `SUSPICIOUS`,
                  `NOT_APPLICABLE`, `UNABLE_TO_EVALUATE` or `ANALYZING`.
              predictionNumber:
                type: number
                nullable: true
                description: >-
                  Raw model score when available, typically 0–1. Not restricted;
                  can be exactly `0` or `1`. `-1` when the model did not
                  evaluate the media.
              normalizedPredictionNumber:
                type: number
                nullable: true
                description: >-
                  Integer 1–99 when evaluated; negative (e.g. `-1`) when the
                  model did not evaluate the media.
              rollingAvgNumber:
                type: number
                nullable: true
                description: >-
                  Rolling average when applicable, with the same normalization
                  as `normalizedPredictionNumber`.
              finalScore:
                type: number
                nullable: true
                description: >-
                  Integer 1–99 when evaluated; negative (e.g. `-1`) when the
                  model did not evaluate the media. Authentic 1–44, Suspicious
                  45–55, Manipulated 56–99 (status `FAKE`).
              data:
                type: object
                nullable: true
                description: >-
                  Model-specific payload, for example `decision`, `score` and
                  `raw_score`. The shape varies by model.
              error:
                description: >-
                  Error details when the model failed. An object, a string or
                  null.
              code:
                type: string
                nullable: true
                description: >-
                  Machine-readable code, for example `not_applicable`; `error`
                  when the model failed.
        rdModels:
          type: array
          items:
            type: object
        storageLocation:
          type: string
          description: >-
            Pre-signed URL of the original uploaded media. May be empty if the
            original was deleted by the retention policy.
        aggregationResultUrl:
          type: string
          description: >-
            Storage key of the scan's `aggregation.json`. Not a downloadable
            URL; use `modelMetadataUrl` instead.
        modelMetadataUrl:
          type: string
          description: >-
            Pre-signed URL of the `aggregation.json` referenced by
            `aggregationResultUrl`. Fetch it to build UI-like visualizations.
        audioModelMetadataUrl:
          type: string
          description: >-
            Pre-signed URL of the extracted-audio aggregation JSON for video
            scans once the audio scan has finished; otherwise `""`.
        explainabilityUrl:
          type: string
          description: >-
            Pre-signed URL of the HTML explainability output, for text scans.
            Always `""` for image, video and audio.
        heatmaps:
          type: object
          description: >-
            Map of model name to pre-signed heatmap PNG URL, one entry per
            `models[]` item.
          additionalProperties:
            type: string
        tags:
          type: array
          description: Labels attached to the scan.
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
    NotFoundError:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            statusCode:
              const: 404
    BaseError:
      type: object
      properties:
        statusCode:
          type: integer
        path:
          type: string
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        code:
          oneOf:
            - type: string
              nullable: true
            - type: number
            - type: boolean
            - type: array
              items:
                type: string
        type:
          type: string
          description: >-
            Present only for import errors (for example
            `unsupported-file-format`).
        name:
          type: string
          description: >-
            Present only for import errors (for example
            `unsupported-file-format`).
        explanation:
          type: string
          description: >-
            Present only for import errors (for example
            `unsupported-file-format`).
    ScanStatus:
      type: string
      description: |-
        Status of a scan:

        - `ANALYZING` — analysis is in progress.
        - `NOT_APPLICABLE` — the media has characteristics known to affect
          accuracy; see `resultsSummary.metadata.reasons`.
        - `UNABLE_TO_EVALUATE` — processing failed, for example a model
          timeout or failure; see `resultsSummary.error`.
        - `DOWNLOADING` — a social media URL is still being downloaded.
        - `DOWNLOAD_FAILED` — the social media URL could not be downloaded;
          see `resultsSummary.error`.
        - `AUTHENTIC` — conclusion Authentic (score typically 1–44).
        - `FAKE` — conclusion Manipulated (score typically 56–99).
        - `SUSPICIOUS` — conclusion Suspicious (score typically 45–55).
      enum:
        - ANALYZING
        - NOT_APPLICABLE
        - UNABLE_TO_EVALUATE
        - DOWNLOADING
        - DOWNLOAD_FAILED
        - AUTHENTIC
        - FAKE
        - SUSPICIOUS
    ScanReason:
      type: object
      description: Why a result is `NOT_APPLICABLE`.
      properties:
        code:
          type: string
          description: >-
            Stable machine-readable code, for example `relevance: no faces
            detected/faces too small`.
        type:
          type: string
          description: >-
            Category of the reason:


            - `Import error` — the media could not be imported.

            - `Not applicable` — the media has characteristics known to affect
            accuracy.

            - `Processing error` — the models failed to process the media.

            - `System error` — a technical failure outside the models.

            - `Download failed` — the social media URL could not be downloaded.
          enum:
            - Import error
            - Not applicable
            - Processing error
            - System error
            - Download failed
        name:
          type: string
          description: Short human-readable title.
        explanation:
          type: string
          description: User-facing explanation.
        rawReason:
          type: string
          description: The detector's original reason string.
      required:
        - code
        - type
        - name
        - explanation
        - rawReason
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        API key created in the web app under API keys. Expired or disabled keys
        are rejected with 401.

````