---
updatedAt: 2025-12-23T13:15:55.000Z
agentTools:
  projectIndex: https://virustotal.readme.io/llms.txt
---

# Get Livehunt notifications

> ❗️ Important
>
> Hunting notifications are no longer showed in the web interface. Use the [/api/v3/ioc\_stream](https://virustotal.readme.io/reference/get-objects-from-the-ioc-stream) endpoint (with `descriptors_only=true`) instead to retrieve IoC-Stream notifications.

> 🚧 Retrieving matching files rather than just notifications
>
> This API endpoint retrieves lists of hunting notification objects, but you may be more interested in retrieving the actual file objects tied to those notifications, you have two different options to do this:
>
> * Ask for the file relation when retrieving the hunting notifications, this will embed the descriptor for the file in the response, which includes the file identifier. This file identifier can then be used to perform a file object lookup via the file endpoint.
>
> * Make use of the [hunting notification files](https://virustotal.readme.io/reference/get-hunting-notification-files) endpoint, which returns a lists of file objects tied to your notifications, along with metadata about the hunting notification match.

This endpoint returns the notifications triggered by your own Livehunt rulesets, or by any other rule owned by somebody else and shared with you.

The `filter` parameter allows to filter the notification according to the values of certain attributes. For example you can get the notifications that are tagged as `my_rule` with `tag:my_rule`. Tags are automatically generated and include the matching file's SHA-256, the ruleset's name, and the identifier for the YARA rule matching the file.

You can also filter the notifications based on the ruleset's owner. With `owner:some_user`, you will get notifications generated by those rules that some\_user shared with you. If you are interested only on those notifications triggered by your own rules, use the `owner` filter with you own user name. You can also combine multiple filters by separating them with spaces, for example: `filter=tag:my_rule owner:foo`.

In addition, it is possible to filter by the notifications date. The date parameter accepts both UTC timestamps or `%Y-%m-%d` date formats with ranges (-, +). For example, `filter=date:1626960086+` returns the notifications that were generated since `Thu 22 Jul 2021 15:21:26 CEST`, `filter=date:2021-07-22-` returns the notifications generated before July 22th, 2021 and `filter=date:2021-07-21+ date:2021-07-23-` returns notifications generated since the July 21th, 2021 and before the July 23th, 2021.

The `order` parameters control the order in which notifications are returned, you can get them by ascending date with `date+`, and by descending date with `date-`.  If no order is specified they will be order by descending date.

For more information check the [Hunting Notification](https://virustotal.readme.io/reference/hunting-notification-object) API object documentation.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "vt-enterprise",
    "version": "3.0"
  },
  "servers": [
    {
      "url": "https://www.virustotal.com/api/v3"
    }
  ],
  "security": [],
  "paths": {
    "/intelligence/hunting_notifications": {
      "get": {
        "summary": "Get Livehunt notifications",
        "description": "",
        "operationId": "list-hunting-notifications",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of notifications to retrieve",
            "schema": {
              "type": "string",
              "default": "10"
            }
          },
          {
            "name": "filter",
            "in": "query",
            "description": "Return the notifications matching the given criteria only",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Continuation cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-apikey",
            "in": "header",
            "description": "Your API key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "count_limit",
            "in": "query",
            "description": "Maximum number of notifications counted (meta.count in the response) 10,000 max",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": false
  },
  "x-readme-fauxas": true
}
```