VirusTotal Private Scanning - Analyses API

openapi: 3.2.0
info:
  title: VirusTotal API v3 - Private Scanning Private Scanning…
  version: '3.0'
  description: Submit files and URLs for analysis without sharing the artefact with the VirusTotal community. Mirrors the public scanning surface (Files / URLs / Analyses / Behaviours / Zip Files).
  contact:
    name: VirusTotal / Google Threat Intelligence
    url: https://docs.virustotal.com/reference/overview
  license:
    name: VirusTotal Terms of Service
    url: https://www.virustotal.com/gui/terms-of-service
  x-generated-from: https://storage.googleapis.com/gtidocresources/guides/GTI_API_v3_openapi_spec_10022025.json
  x-last-validated: '2026-05-29'
servers:
- url: https://www.virustotal.com/api/v3
  description: VirusTotal / GTI API v3 production.
security:
- VTApiKey: []
tags:
- name: Private Scanning - Analyses
  description: Private Scanning - Analyses
paths:
  /private/analyses:
    get:
      tags:
      - Private Scanning - Analyses
      deprecated: false
      description: '> 🚧 Special privileges required

        >

        > Private Scanning endpoints are only available to users with Private Scanning license.


        Returns a list of the last private analyses. The analyses are sorted by most recent first. You can use `?order=date-` to reverse the order.


        ```json /api/v3/private/analyses

        {

        "meta": {

        "cursor": ,

        "count":

        },

        "data": {

        ,

        ,

        ...

        },

        "links": {

        "self": ,

        "next":

        }

        }

        ```

        ```json

        {

        "meta": {

        "count": 90,

        "cursor": "1"

        },

        "data": [

        {

        "attributes": {

        "status": "completed",

        "sandbox_status": {

        "Zenbox": {

        "status": "finished",

        "in_progress_percent": 100

        }

        },

        "sandbox_configuration": {

        "enable_internet": false,

        "command_line": ""

        },

        "date": 1666170912

        },

        "type": "private_analysis",

        "id": "NTJjNTM1MThmMzhiNWRiNGE1ZWQ5ZDhiZjQyNWY2NzM6NTJjMjllYmQ3MThjODM2OWRjNmFiNmIzOTc2MmM3OTY6MTY2NjE3MDkxMg==",

        "links": {

        "item": "https://www.virustotal.com/api/v3/private/files/16f6c6439c5b971218b9cd1d616ba40c7cad08c94984ecfde443dfa3c61c6152",

        "self": "https://www.virustotal.com/api/v3/private/analyses/NTJjNTM1MThmMzhiNWRiNGE1ZWQ5ZDhiZjQyNWY2NzM6NTJjMjllYmQ3MThjODM2OWRjNmFiNmIzOTc2MmM3OTY6MTY2NjE3MDkxMg=="

        }

        }

        ],

        "links": {

        "self": "https://www.virustotal.com/api/v3/private/analyses?limit=1",

        "next": "https://www.virustotal.com/api/v3/private/analyses?cursor=1&limit=1"

        }

        }

        ```'
      operationId: listPrivateAnalyses
      parameters:
      - description: Maximum number of files to retrieve (40 max)
        in: query
        name: limit
        schema:
          default: 10
          format: int32
          type: integer
      - description: Continuation cursor
        in: query
        name: cursor
        schema:
          type: string
      - description: Sorting order
        in: query
        name: order
        schema:
          default: date-
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '200'
        '400':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '400'
      summary: VirusTotal List Private Analyses
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/analyses/{id}:
    get:
      tags:
      - Private Scanning - Analyses
      deprecated: false
      description: '> 🚧 Special privileges required

        >

        > Private Scanning endpoints are only available to users with Private Scanning license.


        With this endpoint you can check the status of a private file analysis. It expects the analysis ID returned by the POST /private/files endpoint, and will return a private analysis object with information about the analysis.


        ```json Example response

        {

        "meta": {

        "file_info": {

        "size": 5,

        "sha256": "11a77c3d96c06974b53d7f40a577e6813739eb5c811b2a86f59038ea90add772",

        "sha1": "7bae8076a5771865123be7112468b79e9d78a640",

        "md5": "e5828c564f71fea3a12dde8bd5d27063"

        }

        },

        "data": {

        "attributes": {

        "date": 1620127014,

        "status": "completed"

        },

        "type": "private_analysis",

        "id": "ZTU4MjhjNTY0ZjcxZmVhM2ExMmRkZThiZDVkMjcwNjM6MTYyMDEyNzAxNA==",

        "links": {

        "self": "https://virustotal.com/api/v3/private/analyses/ZTU4MjhjNTY0ZjcxZmVhM2ExMmRkZThiZDVkMjcwNjM6MTYyMDEyNzAxNA=="

        }

        }

        }

        ```


        The `status` attribute in the private analysis object can be either "queued" or "completed", once it gets completed, you can use the `sha256` in the `file_info` section with the GET /private/files/{id} for getting all the information that VirusTotal has generated for the analysed file. Alternatively you could use GET /private/analyses/{id}/item for the same purpose.'
      operationId: privateAnalysis
      parameters:
      - description: Analysis identifier
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '200'
        '400':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '400'
      summary: VirusTotal Get a Private Analysis
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/analyses/{id}/relationships/{relationship}:
    get:
      tags:
      - Private Scanning - Analyses
      deprecated: false
      description: '> 🚧 Special privileges required

        >

        > Private Scanning endpoints are only available to users with Private Scanning license.


        This endpoint is the same as /private/analyses/{id}/{relationship} except it returns just the related object''s IDs (and context attributes, if any) instead of returning all attributes.'
      operationId: analysesidrelationshipsrelationship
      parameters:
      - description: Analysis identifier
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:private-analyses-object#relationships))
        in: path
        name: relationship
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '200'
        '400':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '400'
      summary: VirusTotal Get Object Descriptors Related to a Private Analysis
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/analyses/{id}/{relationship}:
    get:
      tags:
      - Private Scanning - Analyses
      deprecated: false
      description: '> 🚧 Special privileges required

        >

        > Private Scanning endpoints are only available to users with Private Scanning license.


        As mentioned in the Relationships section, those related objects can be retrieved by sending `GET` requests to the relationship URL.


        Available relationships are described in the private analysis object documentation.'
      operationId: analysesidrelationship
      parameters:
      - description: Analysis identifier
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:private-analyses-object#relationships))
        in: path
        name: relationship
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '200'
        '400':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '400'
      summary: VirusTotal Get Objects Related to a Private Analysis
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    VTApiKey:
      type: apiKey
      in: header
      name: x-apikey
      description: Personal VirusTotal / GTI API key. Found in the user menu of your VirusTotal account.