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.