--- updatedAt: 2026-04-29T22:56:06.000Z agentTools: projectIndex: https://docs.greynoise.io/llms.txt --- # GNQL V3 Recall Get hourly GNQL records for a given time range. # 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": "Recall", "description": "Endpoint that are used for retrieving GNQL data over time. Allows users\nto view hourly snapshots of IP activity for IPs that return for any\nGNQL query.\n" } ], "security": [ { "APIKeyHeaderAuth": [] } ], "paths": { "/v3/gnql/timeseries": { "get": { "tags": [ "Recall" ], "summary": "GNQL V3 Recall", "operationId": "gnqlTimeSeries", "description": "Get hourly GNQL records for a given time range.\n", "parameters": [ { "$ref": "#/components/parameters/query" }, { "in": "query", "name": "start", "description": "Start date for the desired time range", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2025-01-01T00:00:00Z" }, { "in": "query", "name": "end", "description": "End date for the desired time range", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2025-01-07T23:59:59Z" }, { "in": "query", "name": "format", "description": "Specifies the desired format of the results. Must be either csv or json.", "required": false, "schema": { "type": "string", "enum": [ "csv", "json" ], "default": "json" } }, { "in": "query", "name": "limit", "description": "Specifies the number of records desired from the backend query. For example, if you specify a limit of 100, you will get the first 100 records for your query, divided up by hour.", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "description": "Specifies the offset at which to apply the limit. With limit, can be used to paginate through a large response. For example, if you specify a limit of 100 and and an offset of 200, you will get the next 100 records starting at the 200th record.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Query successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesResponse" } } } }, "206": { "description": "Partial content - request partially successful.\nDue to plan limitations, your request only returned a subset of\nfields and/or data. Contact sales@greynoise.io to upgrade your\nplan and unlock full results.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeSeriesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/ExceededLimit" } } } } }, "servers": [ { "url": "https://api.greynoise.io" }, { "url": "http://api.greynoise.io" } ], "components": { "securitySchemes": { "APIKeyHeaderAuth": { "type": "apiKey", "in": "header", "name": "key" } }, "responses": { "BadRequest": { "description": "Bad request - request syntax is invalid for the specified endpoint.\nVerify request syntax and try again.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "example": { "message": "Invalid parameter" } } } }, "Unauthorized": { "description": "Unauthorized. Please check your API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "example": { "message": "Unauthorized" } } } }, "ExceededLimit": { "description": "Too many requests. You've hit the rate-limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" }, "example": { "message": "You've hit the rate limit for this endpoint." } } } } }, "parameters": { "query": { "name": "query", "in": "query", "description": "GNQL query string", "required": true, "schema": { "type": "string" } } }, "schemas": { "ErrorMessage": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "MetadataV3": { "properties": { "mobile": { "type": "boolean", "description": "Defines if the IP is part of a known cellular network.", "example": false }, "source_country": { "type": "string", "description": "Country where the IP address is registered or operates.", "example": "United States" }, "source_country_code": { "type": "string", "description": "Country code of the IP address based on ISO 3166-1 alpha-2.", "example": "US" }, "source_city": { "type": "string", "description": "The city where the device is geographically located.", "example": "Seattle" }, "region": { "type": "string", "description": "The region where the device is geographically located.", "example": "Seattle" }, "organization": { "type": "string", "description": "The name of organization that owns the IP address.", "example": "DigitalOcean, LLC" }, "rdns": { "type": "string", "description": "The reverse DNS pointer.", "example": "crawl-66-249-79-17.googlebot.com" }, "asn": { "type": "string", "description": "The autonomous system identification number.", "example": "AS521" }, "asn_subnet": { "type": "string", "description": "The latest-observed ASN subnet for the IP in GreyNoise scan data, not authoritative current BGP state.", "example": "203.0.113.0/24" }, "category": { "type": "string", "description": "The subset of network types the IP address belongs to.", "enum": [ "isp", "business", "hosting", "mobile", "education" ], "example": "education" }, "os": { "type": "string", "description": "An approximate guess of the operating system of the device, based on the TCP stack fingerprint.", "example": "Windows 7/8" }, "destination_countries": { "type": "array", "items": { "type": "string", "description": "The full name or country code where GreyNoise sensor\nis physically located.\n", "example": "Germany" } }, "destination_country_codes": { "type": "array", "items": { "type": "string", "description": "The country codes where GreyNoise sensor is\nphysically located.\n", "example": "Germany" } }, "destination_cities": { "type": "array", "items": { "type": "string", "description": "The city where the GreyNoise sensor is geographically located.\n", "example": "Berlin" } }, "destination_asns": { "type": "array", "items": { "type": "string", "description": "The ASN associated with the destination IP address.\n", "example": "AS1234" } }, "single_destination": { "type": "boolean", "description": "A Boolean parameter indicating whether the source IP address\nhas only been observed in a single destination country.\n", "example": true }, "carrier": { "type": "string", "description": "The Internet Service Provider (ISP) or telecommunications\ncarrier associated with the source IP address.\n", "example": "AIS" }, "datacenter": { "type": "string", "description": "The datacenter or hosting provider from which the activity originates.\nThis could indicate the use of cloud services,\nmanaged hosting, or enterprise datacenter infrastructure.\n", "example": "us-west-1" }, "domain": { "type": "string", "description": "The domain name associated with the source IP address.\n", "example": "example.com" }, "rdns_parent": { "type": "string", "description": "The parent domain retrieved through reverse DNS (RDNS)\nlookup of the source IP address.\n", "example": "example.com" }, "rdns_validated": { "type": "boolean", "description": "A validation status that confirms whether the reverse DNS (RDNS)\nrecord correctly maps to the source domain.\n", "example": true }, "latitude": { "type": "number", "description": "The geographic latitude of the source IP address.\n", "example": 37.7749 }, "longitude": { "type": "number", "description": "The geographic longitude of the source IP address.\n", "example": -122.4194 }, "sensor_count": { "type": "integer", "description": "Number of sensors with events observed.\n", "example": 10 }, "sensor_hits": { "type": "integer", "description": "Number of scanning events observed.\n", "example": 10 } } }, "TimeSeriesResponse": { "type": "object", "description": "Response object for the timeseries endpoint. The response is a map\nwhere keys are time intervals and values are arrays of IP records\nobserved in that interval.\n\nTime interval keys are formatted as YYYY-MM-DD-HH (e.g., \"2025-01-15-14\")\n", "additionalProperties": { "description": "Time interval key (format: YYYY-MM-DD-HH)\n", "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesRecord" } }, "example": { "2025-11-10-14": [ { "ip": "203.0.113.45", "internet_scanner_intelligence": { "first_seen": "2018-01-28", "last_seen": "2018-02-28", "found": true, "tags": [ "Mirai", "Telnet Worm" ], "actor": "Shodan.io", "spoofable": true, "classification": "benign", "cves": [ "CVE-2020-1234", "CVE-2021-2345" ], "vpn": true, "vpn_service": "IPVANISH_VPN", "tor": false, "last_seen_timestamp": "2025-01-15T12:30:45Z", "metadata": { "asn": "AS13335", "source_country": "United States", "source_country_code": "US", "organization": "Example Hosting" }, "raw_data": { "scan": [ { "port": 22, "protocol": "tcp" } ] } } } ] } }, "TimeSeriesRecord": { "type": "object", "description": "A single IP record in a timeseries response", "properties": { "ip": { "type": "string", "description": "The IP address", "example": "203.0.113.45" }, "internet_scanner_intelligence": { "$ref": "#/components/schemas/TimeSeriesIntelligence" } } }, "TimeSeriesIntelligence": { "type": "object", "description": "Intelligence data for an IP in the timeseries dataset", "properties": { "first_seen": { "type": "string", "description": "The earliest date GreyNoise observed any activity from this IP.", "format": "date", "example": "2018-01-28" }, "last_seen": { "type": "string", "description": "The most recent date GreyNoise observed any activity from this IP.", "format": "date", "example": "2018-02-28" }, "found": { "type": "boolean", "description": "Indicates if the IP was observed scanning the GreyNoise sensor network. Also referred to as 'noise'.", "example": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "A list of activity/malware tags GreyNoise has applied to this\nIP.\n", "example": [ "Mirai", "Telnet Worm" ] }, "actor": { "type": "string", "description": "The overt actor this IP is associated with.", "example": "Shodan.io" }, "spoofable": { "type": "boolean", "description": "This IP address has been opportunistically scanning the Internet, however has failed to complete a full TCP connection. Any reported activity could be spoofed.", "example": true }, "classification": { "type": "string", "description": "The classification of the IP address, either \"benign\", \"malicious\", or \"unknown\", based on the activity observed by GreyNoise.", "enum": [ "benign", "malicious", "unknown" ], "example": "benign" }, "cves": { "type": "array", "items": { "type": "string" }, "description": "A list of CVEs associate with this IP.", "example": [ "CVE-2020-1234", "CVE-2021-2345" ] }, "vpn": { "type": "boolean", "description": "This IP is associated with a VPN service. Activity, malicious or otherwise, should not be attributed to the VPN service provider.", "example": true }, "vpn_service": { "type": "string", "description": "Name of associated VPN Service.", "example": "IPVANISH_VPN" }, "tor": { "type": "boolean", "description": "Whether or not the device is a known Tor exit node.", "example": false }, "last_seen_timestamp": { "type": "string", "description": "The timestamp of the last observed activity from this IP.", "format": "date-time", "example": "2025-01-15T12:30:45Z" }, "metadata": { "$ref": "#/components/schemas/MetadataV3" }, "raw_data": { "$ref": "#/components/schemas/TimeSeriesRawData" } } }, "TimeSeriesRawData": { "type": "object", "description": "Raw data collected about the IP's scanning activity", "properties": { "scan": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesScanEntry" }, "description": "Observed scan activity" }, "ja3": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesJA3Entry" }, "description": "JA3 TLS fingerprints observed" }, "hassh": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesHASSHEntry" }, "description": "HASSH SSH fingerprints observed" }, "http": { "$ref": "#/components/schemas/TimeSeriesHTTPData" }, "source": { "$ref": "#/components/schemas/TimeSeriesSourceData" }, "tls": { "$ref": "#/components/schemas/TimeSeriesTLSData" }, "ssh": { "$ref": "#/components/schemas/TimeSeriesSSHData" }, "tcp": { "$ref": "#/components/schemas/TimeSeriesTCPData" } } }, "TimeSeriesScanEntry": { "type": "object", "properties": { "port": { "type": "integer", "description": "Port number", "example": 80 }, "protocol": { "type": "string", "description": "Protocol", "example": "TCP" } } }, "TimeSeriesJA3Entry": { "type": "object", "properties": { "fingerprint": { "type": "string", "example": "c3a6cf0bf2e690ac8e1ecf6081f17a50", "description": "JA3 hash fingerprint string" }, "port": { "type": "integer", "example": 443, "description": "TCP port connection that the SSL/TLS communication occurred over" } } }, "TimeSeriesHASSHEntry": { "type": "object", "properties": { "fingerprint": { "type": "string", "example": "51cba57125523ce4b9db67714a90bf6e", "description": "HASSH hash fingerprint string" }, "port": { "type": "integer", "example": 2222, "description": "TCP port connection where the HASSH hash was identified\n" } } }, "TimeSeriesHTTPData": { "type": "object", "description": "HTTP-related data observed", "properties": { "md5": { "type": "array", "items": { "type": "string" }, "description": "MD5 hashes of the body content. These compact,\nunique representations of the data allow for quick\ncomparisons and deduplication of payloads without\nstoring the raw content.\n", "example": [ "9764955b67107eeb9edfae76f429e783" ] }, "cookie_keys": { "type": "array", "items": { "type": "string" }, "description": "The keys or names of cookies exchanged in the communication.\nThese can reveal session identifiers, tracking mechanisms,\nor other metadata used in web interactions,\nproviding clues about application behavior or vulnerabilities.\n", "example": [ "expremotekey" ] }, "request_authorization": { "type": "array", "items": { "type": "string" }, "description": "The contents of the Authorization header in a request,\nwhich can include credentials, tokens, or other authentication\ninformation.\n", "example": [ "Bearer exampletoken", "Basic username:password" ] }, "request_cookies": { "type": "array", "items": { "type": "string" }, "description": "Key-value pairs stored in cookies sent with an HTTP request.\nThese cookies often contain session identifiers, user preferences,\nor tracking data, which can be analyzed to detect unauthorized\naccess or manipulation.\n", "example": [ "session_id=1234567890" ] }, "request_header": { "type": "array", "items": { "type": "string" }, "description": "Request Headers are the keys (names) of HTTP headers\nthat a client sends to a server.\n", "example": [ "Content-Type: application/json", "Accept: application/json" ] }, "method": { "type": "array", "items": { "type": "string" }, "description": "The HTTP method used in the request, such as GET, POST, PUT, or DELETE.\nAnalyzing methods can reveal the intent of the request,\nsuch as retrieving or modifying resources,\nand identify unexpected or suspicious activity.\n", "example": [ "GET", "POST", "PUT", "DELETE" ] }, "path": { "type": "array", "items": { "type": "string" }, "description": "Observed scanning activity traversed this web path.", "example": [ "/robots.txt" ] }, "request_origin": { "type": "array", "items": { "type": "string" }, "description": "Indicates the origin of the request,\ntypically used in cross-origin resource sharing (CORS)\nto specify where the request originated.\nThis helps identify unauthorized or potentially\nmalicious cross-origin requests.\n", "example": [ "111.111.1.1" ] }, "useragent": { "type": "array", "items": { "type": "string" }, "description": "Observed scanning activity used these user agents.", "example": [ "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)\n" ] }, "ja4h": { "type": "array", "items": { "type": "string" }, "description": "List of JA4H HTTP client fingerprints observed in network traffic from the IP.\nJA4H captures characteristics of HTTP client behavior including method,\nheaders, and cookie fields, useful for identifying and tracking HTTP clients.\n", "example": [ "ge11cn060000_4e59edc1297a_4da5efaf0cbd" ] } } }, "TimeSeriesSourceData": { "type": "object", "description": "Source traffic metadata", "properties": { "bytes": { "type": "integer", "format": "int64", "description": "The total amount of data transferred (in bytes) during the\nobserved session or connection.\n", "example": 1024 } } }, "TimeSeriesTLSData": { "type": "object", "description": "TLS-related data", "properties": { "cipher": { "type": "array", "items": { "type": "string" }, "description": "The encryption algorithms or cipher suites used during secure\ncommunication. Identifying the ciphers helps assess the security\nof the connection, particularly in TLS/SSL traffic.\n", "example": [ "TLS_AES_128_GCM_SHA256", "TLS_AES_256_GCM_SHA384" ] }, "ja4": { "type": "array", "items": { "type": "string" }, "description": "List of JA4 TLS fingerprints observed in network traffic from the IP.\nJA4 is a modern fingerprinting method that captures distinctive\ncharacteristics of TLS client behavior,\nuseful for identifying and clustering malicious or anomalous clients.\n", "example": [ "t13d1516h2_8daaf6152771_02713d6af862" ] } } }, "TimeSeriesSSHData": { "type": "object", "description": "SSH-related data", "properties": { "key": { "type": "array", "items": { "type": "string" }, "description": "This is the SSH key used.\n", "example": [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890" ] }, "ja4ssh": { "type": "array", "items": { "type": "string" }, "description": "List of JA4SSH fingerprints observed in network traffic from the IP.\nJA4SSH captures SSH traffic patterns including packet lengths and\ndirections, useful for identifying SSH client behavior and detecting\nanomalous sessions.\n", "example": [ "c76s76_c71s59_c0s0" ] } } }, "TimeSeriesTCPData": { "type": "object", "description": "TCP-related data", "properties": { "ja4t": { "type": "array", "items": { "type": "string" }, "description": "List of JA4T TCP fingerprints observed in network traffic from the IP.\nJA4T captures TCP connection characteristics such as window size,\noptions, and MSS, useful for OS fingerprinting and identifying\nnetwork stacks.\n", "example": [ "64240_2-1-3-1-1-4_1460_8" ] }, "ja4l": { "type": "string", "description": "JA4L light distance/latency fingerprint observed in network traffic\nfrom the IP. Captures TCP TTL and window size characteristics, useful\nfor estimating client-server distance and identifying proxied\nconnections.\n", "example": "1460_64" } } } } } } ```