VirusTotal Private Scanning - Analyses API

openapi: 3.0.3
info:
  title: VirusTotal API v3 - Access Control Access Control - Group Management Private Scanning - Analyses API
  version: '3.0'
  description: Manage users, groups, service accounts, API quotas, and overall account usage in VirusTotal / Google Threat Intelligence.
  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: "> \U0001F6A7 Special privileges required\n> \n> Private Scanning endpoints are only available to users with [Private Scanning license](https://www.virustotal.com/gui/private-scanning-overview).\n\nReturns a list of the last [private analyses](https://gtidocs.virustotal.com/reference/private-analyses-object). The analyses are sorted by most recent first. You can use `?order=date-` to reverse the order.\n\n```json /api/v3/private/analyses\n{\n  \"meta\": {\n    \"cursor\": <string>,\n    \"count\": <int>\n  },\n  \"data\": {\n    <PRIVATE_ANALYSIS_OBJECT>,\n    <PRIVATE_ANALYSIS_OBJECT>,\n    ...\n  },\n  \"links\": {\n    \"self\": <string>,\n    \"next\": <string>\n  }\n}\n```\n```json\n{\n\t\"meta\": {\n\t\t\"count\": 90,\n\t\t\"cursor\": \"1\"\n\t},\n\t\"data\": [\n\t\t{\n\t\t\t\"attributes\": {\n\t\t\t\t\"status\": \"completed\",\n\t\t\t\t\"sandbox_status\": {\n\t\t\t\t\t\"Zenbox\": {\n\t\t\t\t\t\t\"status\": \"finished\",\n\t\t\t\t\t\t\"in_progress_percent\": 100\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\t\"sandbox_configuration\": {\n\t\t\t\t\t\"enable_internet\": false,\n\t\t\t\t\t\"command_line\": \"\"\n\t\t\t\t},\n\t\t\t\t\"date\": 1666170912\n\t\t\t},\n\t\t\t\"type\": \"private_analysis\",\n\t\t\t\"id\": \"NTJjNTM1MThmMzhiNWRiNGE1ZWQ5ZDhiZjQyNWY2NzM6NTJjMjllYmQ3MThjODM2OWRjNmFiNmIzOTc2MmM3OTY6MTY2NjE3MDkxMg==\",\n\t\t\t\"links\": {\n\t\t\t\t\"item\": \"https://www.virustotal.com/api/v3/private/files/16f6c6439c5b971218b9cd1d616ba40c7cad08c94984ecfde443dfa3c61c6152\",\n\t\t\t\t\"self\": \"https://www.virustotal.com/api/v3/private/analyses/NTJjNTM1MThmMzhiNWRiNGE1ZWQ5ZDhiZjQyNWY2NzM6NTJjMjllYmQ3MThjODM2OWRjNmFiNmIzOTc2MmM3OTY6MTY2NjE3MDkxMg==\"\n\t\t\t}\n\t\t}\n\t],\n\t\"links\": {\n\t\t\"self\": \"https://www.virustotal.com/api/v3/private/analyses?limit=1\",\n\t\t\"next\": \"https://www.virustotal.com/api/v3/private/analyses?cursor=1&limit=1\"\n\t}\n}\n```\n"
      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: "> \U0001F6A7 Special privileges required\n> \n> Private Scanning endpoints are only available to users with [Private Scanning license](https://www.virustotal.com/gui/private-scanning-overview).\n\nWith this endpoint you can check the status of a private file analysis. It expects the analysis ID returned by the [POST /private/files](https://gtidocs.virustotal.com/reference/upload-file-private-scanning) endpoint, and will return a private analysis object with information about the analysis.\n\n```json Example response\n{\n  \"meta\": {\n    \"file_info\": {\n      \"size\": 5,\n      \"sha256\": \"11a77c3d96c06974b53d7f40a577e6813739eb5c811b2a86f59038ea90add772\",\n      \"sha1\": \"7bae8076a5771865123be7112468b79e9d78a640\",\n      \"md5\": \"e5828c564f71fea3a12dde8bd5d27063\"\n    }\n  },\n  \"data\": {\n    \"attributes\": {\n      \"date\": 1620127014,\n      \"status\": \"completed\"\n    },\n    \"type\": \"private_analysis\",\n    \"id\": \"ZTU4MjhjNTY0ZjcxZmVhM2ExMmRkZThiZDVkMjcwNjM6MTYyMDEyNzAxNA==\",\n    \"links\": {\n      \"self\": \"https://virustotal.com/api/v3/private/analyses/ZTU4MjhjNTY0ZjcxZmVhM2ExMmRkZThiZDVkMjcwNjM6MTYyMDEyNzAxNA==\"\n    }\n  }\n}\n```\n\nThe `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}](https://gtidocs.virustotal.com/reference/private-files-info) for getting all the information that VirusTotal has generated for the analysed file. Alternatively you could use [GET /private/analyses/{id}/item](https://gtidocs.virustotal.com/reference/analysesidrelationship) for the same purpose.\n"
      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: "> \U0001F6A7 Special privileges required\n> \n> Private Scanning endpoints are only available to users with [Private Scanning license](https://www.virustotal.com/gui/private-scanning-overview).\n\nThis endpoint is the same as [/private/analyses/{id}/{relationship}](https://gtidocs.virustotal.com/reference/analysesidrelationship) except it returns just the related object's IDs (and context attributes, if any) instead of returning all attributes.\n"
      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: "> \U0001F6A7 Special privileges required\n> \n> Private Scanning endpoints are only available to users with [Private Scanning license](https://www.virustotal.com/gui/private-scanning-overview).\n\nAs mentioned in the [Relationships](https://gtidocs.virustotal.com/reference/relationships) section, those related objects can be retrieved by sending `GET` requests to the relationship URL. \n\nAvailable relationships are described in the [private analysis](https://gtidocs.virustotal.com/reference/private-analyses-object) object documentation.\n"
      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.