VirusTotal YARA Hunting - Retrohunt API

openapi: 3.0.3
info:
  title: VirusTotal API v3 - Access Control Access Control - Group Management YARA Hunting - Retrohunt 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: YARA Hunting - Retrohunt
  description: YARA Hunting - Retrohunt
paths:
  /intelligence/retrohunt_jobs:
    get:
      tags:
      - YARA Hunting - Retrohunt
      deprecated: false
      description: 'Returns a list of [Retrohunt Job](https://gtidocs.virustotal.com/reference/retrohunt-job-object) objects. Accepted filters are `status:(starting|running|aborting|aborted|finished)`.

        '
      operationId: getRetrohuntJobs
      parameters:
      - description: Maximum number jobs to retrieve
        in: query
        name: limit
        schema:
          default: 10
          format: int32
          type: integer
      - description: Return the jobs matching the given criteria only
        in: query
        name: filter
        schema:
          type: string
      - 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 a List of Retrohunt Jobs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - YARA Hunting - Retrohunt
      deprecated: false
      description: "This endpoint creates a new Retrohunt job. The request's body must have the following structure:\n\n```json Example request\n{\n  \"data\": {\n    \"type\": \"retrohunt_job\",\n    \"attributes\": {\n      \"rules\": \"rule foobar { strings: $ = \\\"foobar\\\" condition: all of them }\",\n      \"notification_email\": \"notifications@acme.com\",\n      \"corpus\": \"main\",\n      \"time_range\": {\n        \"start\": 1545145761,\n        \"end\": 1547737720\n      }\n    }\n  }\n}\n```\n\nThe `rules` attribute is required, but `notification_email`, `corpus` and `time_range` are optional. You should provide  `notification_email` if you want to receive an email notification when the job is finished, while `corpus` allows you to select which dataset you want to scan with your job. There are two different corpuses: \"main\" and \"goodware\". The \"main\" corpus is the default one, composed of files sent to Google Threat Intelligence during the last few months. The \"goodware\" corpus is a random selection of ~1.000.000 files from the [NSRL](https://www.nist.gov/software-quality-group/national-software-reference-library-nsrl) that are not detected by any antivirus engine. This corpus contains multiple file types, and is useful for testing your YARA rules for false positives. If the `corpus` attribute is not specified the \"main\" corpus will be used.\n\n> \U0001F6A7 Retrohunt limits\n> \n> Each user can run up to 10 Retrohunt jobs at the same time, when you reach that limit you must wait for one of the running jobs to finish before launching a new one. Additionally, each job can contain up to 300 YARA rules.\n\nIf you want your job to scan files sent to Google TI within a certain time range you can use the  `time_range` attribute to specify the desired range. Both the `start` and `end` fields in `time_range` should be the UNIX timestamp for the minimum and upper bound of the time range in UTC, and they should be within the maximum range allowed by your Retrohunt privileges. All users can scan up to 90 days back, and this can go up to 180 or 365 days for more privileged users. If `start` is not specified your Retrohunt job will scan back to the limit allowed by your privileges, and if `end` is not specified it will scan up to the most recent files.\n\nReturns the newly created [Retrohunt Job](https://gtidocs.virustotal.com/reference/retrohunt-job-object) object.\n"
      operationId: createRetrohuntJob
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                data:
                  default: '{     "type": "retrohunt_job",     "attributes": {       "rules": "rule foobar { strings: $ = \"foobar\" condition: all of them }",       "corpus": "main"    }   }'
                  description: A Retrohunt job
                  format: json
                  type: string
              required:
              - data
              type: object
      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 Create a New Retrohunt Job
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /intelligence/retrohunt_jobs/{id}:
    delete:
      tags:
      - YARA Hunting - Retrohunt
      deprecated: false
      description: VirusTotal Delete a Retrohunt Job
      operationId: deleteRetrohuntJob
      parameters:
      - description: Job 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'
      security:
      - VTApiKey: []
      summary: VirusTotal Delete a Retrohunt Job
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      tags:
      - YARA Hunting - Retrohunt
      deprecated: false
      description: 'Returns a [Retrohunt Job](https://gtidocs.virustotal.com/reference/retrohunt-job-object) object.

        '
      operationId: getRetrohuntJob
      parameters:
      - description: Job 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'
      security:
      - VTApiKey: []
      summary: VirusTotal Get a Retrohunt Job Object
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /intelligence/retrohunt_jobs/{id}/abort:
    post:
      tags:
      - YARA Hunting - Retrohunt
      deprecated: false
      description: VirusTotal Abort a Retrohunt Job
      operationId: abortRetrohuntJob
      parameters:
      - description: Job 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'
      security:
      - VTApiKey: []
      summary: VirusTotal Abort a Retrohunt Job
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /intelligence/retrohunt_jobs/{id}/matching_files:
    get:
      tags:
      - YARA Hunting - Retrohunt
      deprecated: false
      description: 'Retrohunt jobs are related to other objects. As mentioned in the [Relationships](https://gtidocs.virustotal.com/reference/relationships) section, those related objects can be retrieved by sending `GET` requests to the relationships URL.


        The supported relationships for Retrohunt jobs are described in the [Retrohunt Jobs](https://gtidocs.virustotal.com/reference/retrohunt-job-object) API object page.

        '
      operationId: getRetrohuntJobRelationships
      parameters:
      - description: Job identifier
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: Continuation cursor
        in: query
        name: cursor
        schema:
          type: string
      - description: Maximum number of matching files to retrieve
        in: query
        name: limit
        schema:
          default: 10
          format: int32
          type: integer
      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 Retrieve Matches for a Retrohunt Job
      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.