VirusTotal Private Scanning - Files Behaviours 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 - Files Behaviours
  description: Private Scanning - Files Behaviours
paths:
  /private/file/{id}/behaviours:
    get:
      tags:
      - Private Scanning - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

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


        Fetches all the Private File Behaviour reports available for a private file.'
      operationId: getAllBehaviourReportsFromAPrivateFile
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: id parameter
      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 the Behaviour Reports from a Private File
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/file_behaviours/{sandbox_id}:
    get:
      tags:
      - Private Scanning - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

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


        Fetches a Private File Behaviour object by ID. It expects the sandbox ID returned by the GET /private/files/{id}/behaviours endpoint.


        ```json Example response

        {

        "data": {

        "attributes": {

        "behash": "3f4a02b305dde56c7c606849289bb194",

        "calls_highlighted": [

        "GetTickCount"

        ],

        "files_opened": [

        "C:\\Windows\\system32\\ws2_32.dll",

        "C:\\Windows\\system32\\UxTheme.dll",

        "C:\\Windows\\system32\\ole32.dll",

        "C:\\Users\\\\Downloads\\putty.hlp",

        "C:\\Users\\\\Downloads\\putty.cnt",

        "C:\\Users\\\\Downloads\\putty.chm",

        "C:\\Windows\\system32\\user32.dll",

        "C:\\Windows\\system32\\advapi32.dll",

        "C:\\Windows\\system32\\ntmarta.dll",

        "C:\\Windows\\WinSxS\\x86_microsoft.windows.common-controls_6595b64144ccf1df_6.0.7601.18837_none_41e855142bd5705d",

        "C:\\Windows\\Fonts\\staticcache.dat"

        ],

        "has_html_report": true,

        "has_pcap": true,

        "modules_loaded": [

        "UxTheme.dll",

        "IMM32.dll",

        "SspiCli.dll",

        "ADVAPI32.dll"

        ],

        "processes_tree": [

        {

        "name": "9f9e74241d59eccfe7040bfdcbbceacb374eda397cc53a4197b59e4f6f380a91.exe",

        "process_id": "2340"

        }

        ],

        "registry_keys_opened": [

        "HKCU\\Software\\SimonTatham\\PuTTY\\Sessions",

        "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\FontLink\\SystemLink",

        "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\LanguagePack\\DataStore_V1.0",

        "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\LanguagePack\\DataStore_V1.0\\Disable",

        "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\LanguagePack\\DataStore_V1.0\\DataFilePath",

        "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\LanguagePack\\SurrogateFallback",

        "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\LanguagePack\\SurrogateFallback\\MS Shell Dlg"

        ],

        "sandbox_name": "VirusTotal Jujubox",

        "tags": [

        "DIRECT_CPU_CLOCK_ACCESS",

        "RUNTIME_MODULES"

        ],

        "text_highlighted": [

        "PuTTY Configuration",

        "&Open",

        "Cate&gory:",

        "C:\\Windows\\system32\\cmd.exe"

        ]

        },

        "id": "9f9e74241d59eccfe7040bfdcbbceacb374eda397cc53a4197b59e4f6f380a91_VirusTotal Jujubox-1658933614",

        "links": {

        "self": "https://www.virustotal.com/api/v3/private/file_behaviours/9f9e74241d59eccfe7040bfdcbbceacb374eda397cc53a4197b59e4f6f380a91_VirusTotal Jujubox-1658933614"

        },

        "type": "private_file_behaviour"

        }

        }

        ```'
      operationId: privatefileBehaviourssandboxId
      parameters:
      - description: Sandbox report ID.
        in: path
        name: sandbox_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 Behaviour Report from a Private File
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/file_behaviours/{sandbox_id}/evtx:
    get:
      tags:
      - Private Scanning - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

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


        Fetch the EVTX file associated with the sandbox execution.'
      operationId: fileBehaviourssandboxIdevtx
      parameters:
      - description: Sandbox report ID
        in: path
        name: sandbox_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 the EVTX File Generated During a Private File’s Behavior Analysis
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/file_behaviours/{sandbox_id}/html:
    get:
      tags:
      - Private Scanning - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

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


        Returns a Private File Behaviour object as an HTML report. It expects the sandbox ID returned by the GET /private/files/{id}/behaviours endpoint.'
      operationId: privatefileBehaviourssandboxIdhtml
      parameters:
      - description: Sandbox report ID
        in: path
        name: sandbox_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            text/plain:
              examples:
                Result:
                  value: "<!DOCTYPE html>\n<html lang=\"en\">\n  ..."
          description: '200'
        '400':
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                properties: {}
                type: object
          description: '400'
      summary: VirusTotal Get a Detailed HTML Behaviour Report
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/file_behaviours/{sandbox_id}/memdump:
    get:
      tags:
      - Private Scanning - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

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


        Fetch the PCAP file associated with the sandbox execution.'
      operationId: privatefileBehaviourssandboxIdpcap
      parameters:
      - description: Sandbox report ID
        in: path
        name: sandbox_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 the Memdump File Generated During a Private File’s Behavior…
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/file_behaviours/{sandbox_id}/pcap:
    get:
      tags:
      - Private Scanning - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

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


        Fetch the memdump file associated with the sandbox execution.'
      operationId: fileBehaviourssandboxIdmemdump
      parameters:
      - description: Sandbox report ID
        in: path
        name: sandbox_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 the PCAP File Generated During a Private File’s Behavior Analysis
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/file_behaviours/{sandbox_id}/relationships/{relationship}:
    get:
      tags:
      - Private Scanning - Files Behaviours
      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/file_behaviours/{sandbox_id}/{relationship} except it returns just the related object''s IDs (and context attributes, if any) instead of returning all attributes.'
      operationId: privatefileBehaviourssandboxIdrelationshipsrelationship
      parameters:
      - description: Sandbox report ID. See "Sandbox Report identifiers" section above for more info.
        in: path
        name: sandbox_id
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:private-file-behaviours-object#relationships))
        in: path
        name: relationship
        required: true
        schema:
          type: string
      - description: Maximum number of related objects to retrieve
        in: query
        name: limit
        schema:
          default: 10
          format: int32
          type: integer
      - description: Continuation cursor
        in: query
        name: cursor
        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 File's Behaviour Report
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/file_behaviours/{sandbox_id}/{relationship}:
    get:
      tags:
      - Private Scanning - Files Behaviours
      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 file behaviour object documentation.'
      operationId: privatefileBehaviourssandboxIdrelationship
      parameters:
      - description: Sandbox report ID. See "Sandbox Report identifiers" section above for more info.
        in: path
        name: sandbox_id
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:private-file-behaviours-object#relationships))
        in: path
        name: relationship
        required: true
        schema:
          type: string
      - description: Maximum number of related objects to retrieve
        in: query
        name: limit
        schema:
          default: 10
          format: int32
          type: integer
      - description: Continuation cursor
        in: query
        name: cursor
        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 File's Behaviour Report
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/files/{id}/behaviour_mitre_trees:
    get:
      tags:
      - Private Scanning - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

        > Private Scanning endpoints are only available to users with Private Scanning license.'
      operationId: getSummaryAllMitreAttackTechniquesObservedInAFile
      parameters:
      - description: File's SHA-256
        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 Summary of All MITRE ATT&CK Techniques Observed in a File
      security:
      - VTApiKey: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /private/files/{id}/behaviour_summary:
    get:
      tags:
      - Private Scanning - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

        > Private Scanning endpoints are only available to users with Private Scanning license.'
      operationId: privatefilesidbehaviourSummary
      parameters:
      - description: File's SHA-256
        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 Summary of All Behavior Reports for a File
      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.