---
updatedAt: 2026-08-20T16:54:44.000Z
agentTools:
  projectIndex: https://docs.greynoise.io/llms.txt
---

# Search retained feed events

Search the authenticated workspace's retained feed-event history without
reading or changing any pull-consumer checkpoint. Results are ordered
newest first.

The simplest request is an empty JSON object. It returns events from all
currently enabled, non-session feeds over the previous hour. Set `from`
to a relative duration such as `6h` or `7d`, a UTC date, or an RFC 3339
timestamp. `to` accepts a UTC date or RFC 3339 timestamp and defaults to
the time the request is received.

For narrower searches, use `feed_ids` and the advanced exact-match fields
`event_types`, `ip`, `cve`, `tag`, and `classification`. Explicitly named
disabled feeds remain searchable while their events are retained.

This endpoint uses stateless keyset pagination. When `has_more` is true,
send a new request containing only the returned `cursor` and, optionally,
`limit`. The signed cursor restores the original workspace, feed scope,
filters, and absolute time window. It is unrelated to the cursor returned
by the pull endpoint for acknowledgement.

Retained history is approximately 90 days. Session events are not stored
and cannot be searched.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "description": "GreyNoise is a cybersecurity company that collects and analyzes Internet-wide scan and attack traffic. Use GreyNoise to contextualize existing alerts, filter false-positives, identify compromised devices, and track emerging threats.",
    "version": "3.0.0",
    "title": "GreyNoise API",
    "contact": {
      "email": "hello@greynoise.io"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.greynoise.io/terms"
    }
  },
  "tags": [
    {
      "name": "Event Feeds",
      "description": "Consume and search workspace-scoped feed events retained for approximately\n90 days.\n\nPull consumers keep their checkpoints on the server. Fetching is read-only;\nacknowledge the returned signed cursor only after processing the complete\nbatch. Event search uses a separate stateless pagination cursor and never\nchanges a pull consumer's checkpoint.\n\nSession events are webhook-only and are not retained, searchable, or\navailable through the pull API. Access depends on the workspace's Feeds and\nEvent Feed API entitlements.\n\nFor an end-to-end integration workflow, see\n[Using the Feeds API to Retrieve Events](https://docs.greynoise.io/docs/using-the-feeds-api-to-retrieve-events).\n"
    }
  ],
  "security": [
    {
      "APIKeyHeaderAuth": []
    }
  ],
  "paths": {
    "/v3/feeds/events/search": {
      "post": {
        "tags": [
          "Event Feeds"
        ],
        "operationId": "SearchFeedEvents",
        "summary": "Search retained feed events",
        "description": "Search the authenticated workspace's retained feed-event history without\nreading or changing any pull-consumer checkpoint. Results are ordered\nnewest first.\n\nThe simplest request is an empty JSON object. It returns events from all\ncurrently enabled, non-session feeds over the previous hour. Set `from`\nto a relative duration such as `6h` or `7d`, a UTC date, or an RFC 3339\ntimestamp. `to` accepts a UTC date or RFC 3339 timestamp and defaults to\nthe time the request is received.\n\nFor narrower searches, use `feed_ids` and the advanced exact-match fields\n`event_types`, `ip`, `cve`, `tag`, and `classification`. Explicitly named\ndisabled feeds remain searchable while their events are retained.\n\nThis endpoint uses stateless keyset pagination. When `has_more` is true,\nsend a new request containing only the returned `cursor` and, optionally,\n`limit`. The signed cursor restores the original workspace, feed scope,\nfilters, and absolute time window. It is unrelated to the cursor returned\nby the pull endpoint for acknowledgement.\n\nRetained history is approximately 90 days. Session events are not stored\nand cannot be searched.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventFeedSearchRequest"
              },
              "examples": {
                "default": {
                  "summary": "Search all enabled feeds over the previous hour",
                  "value": {}
                },
                "feedHistory": {
                  "summary": "Search one feed over the previous day",
                  "value": {
                    "feed_ids": [
                      "5575f06f-97fa-435a-a176-7682a4fbc92f"
                    ],
                    "from": "1d",
                    "limit": 100
                  }
                },
                "absoluteWindow": {
                  "summary": "Search an explicit UTC date range",
                  "value": {
                    "from": "2026-08-01",
                    "to": "2026-08-08"
                  }
                },
                "maliciousIPs": {
                  "summary": "Advanced exact-match filters",
                  "value": {
                    "from": "6h",
                    "event_types": [
                      "ip-classification-change"
                    ],
                    "ip": "198.51.100.42",
                    "classification": "malicious",
                    "limit": 100
                  }
                },
                "nextPage": {
                  "summary": "Continue a search using its signed cursor",
                  "value": {
                    "cursor": "eyJ2IjoyLCJwIjoic2VhcmNoIiwiLi4uIn0.signature",
                    "limit": 100
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A newest-first page of matching retained events.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventFeedSearchResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/EventFeedBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/EventFeedUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EventFeedForbidden"
          },
          "404": {
            "$ref": "#/components/responses/EventFeedNotFound"
          },
          "408": {
            "$ref": "#/components/responses/EventFeedRequestTimeout"
          },
          "410": {
            "$ref": "#/components/responses/EventFeedGone"
          },
          "500": {
            "$ref": "#/components/responses/EventFeedUnexpectedError"
          },
          "502": {
            "$ref": "#/components/responses/EventFeedBadGateway"
          },
          "504": {
            "$ref": "#/components/responses/EventFeedGatewayTimeout"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.greynoise.io"
    },
    {
      "url": "http://api.greynoise.io"
    }
  ],
  "components": {
    "securitySchemes": {
      "APIKeyHeaderAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "key"
      }
    },
    "responses": {
      "EventFeedBadRequest": {
        "description": "A path parameter, query parameter, request body, filter, or cursor is invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "bad request",
              "code": 400
            }
          }
        }
      },
      "EventFeedUnauthorized": {
        "description": "The API key or authenticated user is missing or invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "unauthorized",
              "code": 401
            }
          }
        }
      },
      "EventFeedForbidden": {
        "description": "The caller cannot access the workspace or the required entitlement is not enabled.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "event feed API entitlement required",
              "code": 403
            }
          }
        }
      },
      "EventFeedNotFound": {
        "description": "The workspace-scoped feed or consumer was not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "not found",
              "code": 404
            }
          }
        }
      },
      "EventFeedRequestTimeout": {
        "description": "The request was canceled before it completed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "request timeout",
              "code": 408
            }
          }
        }
      },
      "EventFeedGone": {
        "description": "The cursor points outside the retained event window. Follow the returned\nrecovery action to fetch from the current retention boundary.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "examples": {
              "acknowledgeCursorExpired": {
                "summary": "An acknowledgement cursor has fallen outside retention",
                "value": {
                  "error": "gone",
                  "code": 410,
                  "recovery": {
                    "action": "fetch_without_cursor"
                  }
                }
              },
              "searchCursorExpired": {
                "summary": "A search cursor has fallen outside retention",
                "value": {
                  "error": "gone",
                  "code": 410,
                  "recovery": {
                    "action": "restart_search"
                  }
                }
              }
            }
          }
        }
      },
      "EventFeedUnexpectedError": {
        "description": "An unexpected error occurred while processing the request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "internal server error",
              "code": 500
            }
          }
        }
      },
      "EventFeedBadGateway": {
        "description": "The Event Feed service was unavailable or returned an invalid response.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "bad gateway",
              "code": 502
            }
          }
        }
      },
      "EventFeedGatewayTimeout": {
        "description": "The Event Feed service did not complete the request before its deadline.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "gateway timeout",
              "code": 504
            }
          }
        }
      }
    },
    "schemas": {
      "EventFeedError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error",
          "code"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Safe, human-readable error message."
          },
          "code": {
            "type": "integer",
            "description": "HTTP status code."
          },
          "recovery": {
            "$ref": "#/components/schemas/EventFeedRecovery"
          }
        }
      },
      "EventFeedRecovery": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "action"
        ],
        "properties": {
          "action": {
            "type": "string",
            "description": "Recovery action for a cursor that has fallen outside retention.",
            "enum": [
              "fetch_without_cursor",
              "restart_search"
            ]
          }
        }
      },
      "EventFeedEventType": {
        "type": "string",
        "description": "Retained event type. `session-received` and `new-tag-activity` events are\nnot retained and therefore are not available to pull consumers or search.\n",
        "enum": [
          "ip-classification-change",
          "cve-status-change",
          "cve-activity-spike",
          "vendor-cve-spike",
          "tag-spike",
          "new-callback-ip",
          "new-callback-file",
          "credential-observed"
        ]
      },
      "EventFeedSearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "For the first page, omit `cursor` and provide any search criteria. An\nempty object searches all enabled feeds over the previous hour.\n\nFor each subsequent page, send `cursor` and optional `limit` only. Search\ncriteria cannot be combined with a cursor because the cursor already\ncontains the original normalized scope and absolute time window.\n",
        "properties": {
          "feed_ids": {
            "type": "array",
            "maxItems": 100,
            "description": "Feed UUIDs to include. Omit to search all currently enabled,\nnon-session feeds in the workspace. Explicit IDs may refer to disabled\nfeeds, but deleted feeds return `404` and session feeds return `400`.\n",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "event_types": {
            "type": "array",
            "maxItems": 8,
            "description": "Advanced filter for exact retained event types.",
            "items": {
              "$ref": "#/components/schemas/EventFeedEventType"
            }
          },
          "ip": {
            "type": "string",
            "maxLength": 45,
            "description": "Advanced filter for an exact IP in the indexed event dimensions.",
            "example": "198.51.100.42"
          },
          "cve": {
            "type": "string",
            "maxLength": 128,
            "description": "Advanced filter for an exact CVE in the indexed event dimensions.",
            "example": "CVE-2026-12345"
          },
          "tag": {
            "type": "string",
            "maxLength": 256,
            "description": "Advanced filter for an exact tag in the indexed event dimensions.",
            "example": "Mirai Variant"
          },
          "classification": {
            "type": "string",
            "maxLength": 128,
            "description": "Advanced filter for an exact classification in the indexed event dimensions.",
            "example": "malicious"
          },
          "from": {
            "description": "Inclusive lower event-time bound. Accepts a positive whole-number\nduration in hours or days relative to `to` (for example `1h`, `6h`,\n`1d`, or `7d`), a UTC date (`YYYY-MM-DD`), or an RFC 3339 timestamp.\nDefaults to one hour before `to`.\n",
            "anyOf": [
              {
                "type": "string",
                "pattern": "^[1-9][0-9]*(h|d)$"
              },
              {
                "type": "string",
                "format": "date",
                "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
              },
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})$"
              }
            ],
            "example": "1h"
          },
          "to": {
            "description": "Exclusive upper event-time bound as a UTC date (`YYYY-MM-DD`) or RFC\n3339 timestamp. Defaults to the time the request is received and must\nbe later than the resolved `from` value.\n",
            "anyOf": [
              {
                "type": "string",
                "format": "date",
                "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
              },
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})$"
              }
            ],
            "example": "2026-08-17T12:00:00Z"
          },
          "cursor": {
            "type": "string",
            "maxLength": 8192,
            "description": "Opaque signed cursor returned by the preceding search page. A\ncontinuation request may contain only this field and optional `limit`.\n"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "default": 100,
            "description": "Maximum number of events to return."
          }
        }
      },
      "EventFeedSearchResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "feed_id",
          "event_type",
          "payload",
          "created_at"
        ],
        "properties": {
          "feed_id": {
            "type": "string",
            "format": "uuid",
            "description": "Feed that matched the retained event."
          },
          "event_type": {
            "$ref": "#/components/schemas/EventFeedEventType"
          },
          "payload": {
            "type": "object",
            "additionalProperties": true,
            "description": "Event-type-specific JSON payload."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Time the event entered the retained feed log."
          }
        }
      },
      "EventFeedSearchRetention": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "oldest_available_at"
        ],
        "properties": {
          "oldest_available_at": {
            "type": "string",
            "format": "date-time",
            "description": "Beginning of the currently retained event window."
          }
        }
      },
      "EventFeedSearchResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "events",
          "has_more",
          "retention"
        ],
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventFeedSearchResult"
            }
          },
          "cursor": {
            "type": "string",
            "maxLength": 8192,
            "description": "Opaque cursor for the next page. Omitted on the final page."
          },
          "has_more": {
            "type": "boolean"
          },
          "retention": {
            "$ref": "#/components/schemas/EventFeedSearchRetention"
          }
        }
      }
    }
  }
}
```