VirusTotal IoC Investigation - Files Behaviours API

openapi: 3.2.0
info:
  title: VirusTotal API v3 - IoC Investigation IoC Investigation…
  version: '3.0'
  description: Investigate files, URLs, IP addresses, and domains. Submit and analyse samples, retrieve reports, get comments and votes, view sandbox behaviour, traverse the relationships graph.
  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: IoC Investigation - Files Behaviours
  description: IoC Investigation - Files Behaviours
paths:
  /file_behaviours/{sandbox_id}:
    get:
      tags:
      - IoC Investigation - Files Behaviours
      deprecated: false
      description: 'Fetches a File behaviour object by ID.


        > 📘 This API call only fetches the behaviour report for a single behavioural analysis you can fetch all of them with https://gtidocs.virustotal.com/reference/file-all-behaviours-summary


        ## Sandbox Report identifiers


        A Sandbox report ID has two main components: the **analysed file''s SHA256** and the **sandbox name**. These two components are joined by a `_` character. For example, ID `5353e23f3653402339c93a8565307c6308ff378e03fcf23a4378f31c434030b0_VirusTotal Jujubox` fetches the sandbox report for a file having a SHA256 `5353e23f3653402339c93a8565307c6308ff378e03fcf23a4378f31c434030b0` analysed in the `VirusTotal Jujubox` sandbox.'
      operationId: getFileBehaviourId
      parameters:
      - description: Sandbox report ID. See "Sandbox Report identifiers" section below for more info.
        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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get a File Behavior Report from a Sandbox
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /file_behaviours/{sandbox_id}/evtx:
    get:
      tags:
      - IoC Investigation - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

        > This endpoint is only available for users with special privileges.


        Fetch the EVTX file associated with the sandbox execution.'
      operationId: fileBehaviourEvtx
      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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get the EVTX File Generated During a File’s Behavior Analysis
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /file_behaviours/{sandbox_id}/html:
    get:
      tags:
      - IoC Investigation - Files Behaviours
      deprecated: false
      description: 'Returns a File behaviour object as an HTML report.


        ## Sandbox Report identifiers


        A Sandbox report ID has two main components: the **analysed file''s SHA256** and the **sandbox name**. These two components are joined by a `_` character. For example, ID `5353e23f3653402339c93a8565307c6308ff378e03fcf23a4378f31c434030b0_VirusTotal Jujubox` fetches the sandbox report for a file having a SHA256 `5353e23f3653402339c93a8565307c6308ff378e03fcf23a4378f31c434030b0` analysed in the `VirusTotal Jujubox` sandbox.'
      operationId: getFileBehaviourHtml
      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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get a Detailed HTML Behaviour Report
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /file_behaviours/{sandbox_id}/memdump:
    get:
      tags:
      - IoC Investigation - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

        > This endpoint is only available for users with special privileges.


        Fetch the memdump file associated with the sandbox execution.'
      operationId: fileBehaviourMemdump
      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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get the Memdump File Generated During a File’s Behavior Analysis
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /file_behaviours/{sandbox_id}/pcap:
    get:
      tags:
      - IoC Investigation - Files Behaviours
      deprecated: false
      description: '> 🚧 Special privileges required

        >

        > This endpoint is only available for users with special privileges.


        Fetch the PCAP file associated with the sandbox execution.'
      operationId: fileBehavioursPcap
      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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get the PCAP File Generated During a File’s Behavior Analysis
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /file_behaviours/{sandbox_id}/relationships/{relationship}:
    get:
      tags:
      - IoC Investigation - Files Behaviours
      deprecated: false
      description: This endpoint is the same as /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: fileBehaviourssandboxIdrelationshipsrelationship
      parameters:
      - description: Sandbox report ID
        in: path
        name: sandbox_id
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:file-behaviour-summary-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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get Object Descriptors Related to a Behaviour Report
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /file_behaviours/{sandbox_id}/{relationship}:
    get:
      tags:
      - IoC Investigation - Files Behaviours
      deprecated: false
      description: '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 File behaviour object documentation.'
      operationId: fileBehaviourssandboxIdrelationship
      parameters:
      - description: Sandbox report ID
        in: path
        name: sandbox_id
        required: true
        schema:
          type: string
      - description: Relationship name (see [table](ref:file-behaviour-summary-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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get Objects Related to a Behaviour Report
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /files/{id}/behaviour_mitre_trees:
    get:
      tags:
      - IoC Investigation - Files Behaviours
      deprecated: false
      description: This endpoint returns a summary of MITRE ATT&CK tactics and techniques observed in each of the sandbox reports of a file.
      operationId: getASummaryOfAllMitreAttckTechniquesObservedInAFile
      parameters:
      - description: SHA-256, SHA-1 or MD5 identifying the file
        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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get a Summary of All MITRE ATT&CK Techniques Observed in a File
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /files/{id}/behaviour_summary:
    get:
      tags:
      - IoC Investigation - Files Behaviours
      deprecated: false
      description: This endpoint returns a summary with behavioural information about the file.
      operationId: fileAllBehavioursSummary
      parameters:
      - description: SHA-256, SHA-1 or MD5 identifying the file
        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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get a Summary of All Behavior Reports for a File
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /files/{id}/behaviours:
    get:
      tags:
      - IoC Investigation - Files Behaviours
      deprecated: false
      description: This endpoint returns behavioural information from each sandbox about the file.
      operationId: getAllBehaviorReportsForAFile
      parameters:
      - description: SHA-256, SHA-1 or MD5 identifying the file
        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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get All Behavior Reports for a File
      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.