openapi: 3.0.0
info:
title: GreyNoise Callback Recall API
version: 3.0.0
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.
contact:
email: hello@greynoise.io
license:
name: Proprietary
url: https://www.greynoise.io/terms
servers:
- url: https://api.greynoise.io
description: Production
security:
- APIKeyHeaderAuth: []
tags:
- name: Recall
description: 'Endpoint that are used for retrieving GNQL data over time. Allows users
to view hourly snapshots of IP activity for IPs that return for any
GNQL query.
'
paths:
/v3/gnql/timeseries:
get:
tags:
- Recall
summary: GNQL V3 Recall
operationId: gnqlTimeSeries
description: 'Get hourly GNQL records for a given time range.
'
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'
examples:
GnqlTimeSeries200Example:
summary: Default gnqlTimeSeries 200 response
x-microcks-default: true
value: &id001
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
'206':
description: 'Partial content - request partially successful.
Due to plan limitations, your request only returned a subset of
fields and/or data. Contact sales@greynoise.io to upgrade your
plan and unlock full results.
'
content:
application/json:
schema:
$ref: '#/components/schemas/TimeSeriesResponse'
examples:
GnqlTimeSeries206Example:
summary: Default gnqlTimeSeries 206 response
x-microcks-default: true
value: *id001
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/ExceededLimit'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/gnql/timeseries/stats:
get:
tags:
- Recall
summary: GNQL V3 Recall Stats
operationId: gnqlTimeSeriesStats
description: 'Get the number of unique IPs that match a GNQL query
per hour/day over a given time range.
'
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: interval
description: Specifies the time interval over which to aggregate unique IPs that return the given GNQL query.
required: true
schema:
type: string
enum:
- hour
- day
responses:
'200':
description: Query successful.
content:
application/json:
schema:
$ref: '#/components/schemas/TimeSeriesStatsResponse'
examples:
GnqlTimeSeriesStats200Example:
summary: Default gnqlTimeSeriesStats 200 response
x-microcks-default: true
value: &id002
count: 1500
min: 10
max: 250
data:
- date: '2025-11-10 14:00:00.000'
count: 125
- date: '2025-11-10 15:00:00.000'
count: 250
- date: '2025-11-10 16:00:00.000'
count: 180
'206':
description: 'Partial content - request partially successful.
Due to plan limitations, your request only returned a subset of
fields and/or data. Contact sales@greynoise.io to upgrade your
plan and unlock full results.
'
content:
application/json:
schema:
$ref: '#/components/schemas/TimeSeriesStatsResponse'
examples:
GnqlTimeSeriesStats206Example:
summary: Default gnqlTimeSeriesStats 206 response
x-microcks-default: true
value: *id002
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/ExceededLimit'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
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'
TimeSeriesSourceData:
type: object
description: Source traffic metadata
properties:
bytes:
type: integer
format: int64
description: 'The total amount of data transferred (in bytes) during the
observed session or connection.
'
example: 1024
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.
JA4T captures TCP connection characteristics such as window size,
options, and MSS, useful for OS fingerprinting and identifying
network stacks.
'
example:
- 64240_2-1-3-1-1-4_1460_8
ja4l:
type: string
description: 'JA4L light distance/latency fingerprint observed in network traffic
from the IP. Captures TCP TTL and window size characteristics, useful
for estimating client-server distance and identifying proxied
connections.
'
example: '1460_64'
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
TimeSeriesSSHData:
type: object
description: SSH-related data
properties:
key:
type: array
items:
type: string
description: 'This is the SSH key used.
'
example:
- ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890
ja4ssh:
type: array
items:
type: string
description: 'List of JA4SSH fingerprints observed in network traffic from the IP.
JA4SSH captures SSH traffic patterns including packet lengths and
directions, useful for identifying SSH client behavior and detecting
anomalous sessions.
'
example:
- c76s76_c71s59_c0s0
TimeSeriesResponse:
type: object
description: 'Response object for the timeseries endpoint. The response is a map
where keys are time intervals and values are arrays of IP records
observed in that interval.
Time interval keys are formatted as YYYY-MM-DD-HH (e.g., "2025-01-15-14")
'
additionalProperties:
description: 'Time interval key (format: YYYY-MM-DD-HH)
'
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
TimeSeriesStatsResponse:
type: object
description: 'Response object for the timeseries stats/aggregation endpoint.
This provides aggregated IP counts over time intervals matching
a GNQL query.
'
properties:
count:
type: integer
description: The sum of all IP counts across all time intervals
example: 1500
min:
type: integer
description: The minimum IP count observed in any single time interval
example: 10
max:
type: integer
description: The maximum IP count observed in any single time interval
example: 250
data:
type: array
items:
$ref: '#/components/schemas/TimeSeriesStatsRecord'
description: Array of aggregated data points, one per time interval
example: []
example:
count: 1500
min: 10
max: 250
data:
- date: '2025-11-10 14:00:00.000'
count: 125
- date: '2025-11-10 15:00:00.000'
count: 250
- date: '2025-11-10 16:00:00.000'
count: 180
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
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
is physically located.
'
example: Germany
example:
- string
destination_country_codes:
type: array
items:
type: string
description: 'The country codes where GreyNoise sensor is
physically located.
'
example: Germany
example:
- US
destination_cities:
type: array
items:
type: string
description: 'The city where the GreyNoise sensor is geographically located.
'
example: Berlin
example:
- string
destination_asns:
type: array
items:
type: string
description: 'The ASN associated with the destination IP address.
'
example: AS1234
example:
- string
single_destination:
type: boolean
description: 'A Boolean parameter indicating whether the source IP address
has only been observed in a single destination country.
'
example: true
carrier:
type: string
description: 'The Internet Service Provider (ISP) or telecommunications
carrier associated with the source IP address.
'
example: AIS
datacenter:
type: string
description: 'The datacenter or hosting provider from which the activity originates.
This could indicate the use of cloud services,
managed hosting, or enterprise datacenter infrastructure.
'
example: us-west-1
domain:
type: string
description: 'The domain name associated with the source IP address.
'
example: example.com
rdns_parent:
type: string
description: 'The parent domain retrieved through reverse DNS (RDNS)
lookup of the source IP address.
'
example: example.com
rdns_validated:
type: boolean
description: 'A validation status that confirms whether the reverse DNS (RDNS)
record correctly maps to the source domain.
'
example: true
latitude:
type: number
description: 'The geographic latitude of the source IP address.
'
example: 37.7749
longitude:
type: number
description: 'The geographic longitude of the source IP address.
'
example: -122.4194
sensor_count:
type: integer
description: 'Number of sensors with events observed.
'
example: 10
sensor_hits:
type: integer
description: 'Number of scanning events observed.
'
example: 10
TimeSeriesTLSData:
type: object
description: TLS-related data
properties:
cipher:
type: array
items:
type: string
description: 'The encryption algorithms or cipher suites used during secure
communication. Identifying the ciphers helps assess the security
of the connection, particularly in TLS/SSL traffic.
'
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.
JA4 is a modern fingerprinting method that captures distinctive
characteristics of TLS client behavior,
useful for identifying and clustering malicious or anomalous clients.
'
example:
- t13d1516h2_8daaf6152771_02713d6af862
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
'
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
IP.
'
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'
TimeSeriesScanEntry:
type: object
properties:
port:
type: integer
description: Port number
example: 80
protocol:
type: string
description: Protocol
example: TCP
TimeSeriesStatsRecord:
type: object
description: A single aggregated data point in a timeseries stats response
properties:
date:
type: string
description: 'The starting timestamp for this time interval in format
''YYYY-MM-DD HH:mm:ss.SSS''.
For hourly intervals, the time component represents the hour.
For daily intervals, the time will be 00:00:00.000.
'
example: '2025-11-10 14:00:00.000'
count:
type: integer
description: 'The number of unique IPs matching the query in this time
interval
'
example: 125
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
example: []
ja3:
type: array
items:
$ref: '#/components/schemas/TimeSeriesJA3Entry'
description: JA3 TLS fingerprints observed
example: []
hassh:
type: array
items:
$ref: '#/components/schemas/TimeSeriesHASSHEntry'
description: HASSH SSH fingerprints observed
example: []
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'
TimeSeriesHTTPData:
type: object
description: HTTP-related data observed
properties:
md5:
type: array
items:
type: string
description: 'MD5 hashes of the body content. These compact,
unique representations of the data allow for quick
comparisons and deduplication of payloads without
storing the raw content.
'
example:
- 9764955b67107eeb9edfae76f429e783
cookie_keys:
type: array
items:
type: string
description: 'The keys or names of cookies exchanged in the communication.
These can reveal session identifiers, tracking mechanisms,
or other metadata used in web interactions,
providing clues about application behavior or vulnerabilities.
'
example:
- expremotekey
request_authorization:
type: array
items:
type: string
description: 'The contents of the Authorization header in a request,
which can include credentials, tokens, or other authentication
information.
'
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.
These cookies often contain session identifiers, user preferences,
or tracking data, which can be analyzed to detect unauthorized
access or manipulation.
'
example:
- session_id=1234567890
request_header:
type: array
items:
type: string
description: 'Request Headers are the keys (names) of HTTP headers
that a client sends to a server.
'
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.
Analyzing methods can reveal the intent of the request,
such as retrieving or modifying resources,
and identify unexpected or suspicious activity.
'
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,
typically used in cross-origin resource sharing (CORS)
to specify where the request originated.
This helps identify unauthorized or potentially
malicious cross-origin requests.
'
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)
'
ja4h:
type: array
items:
type: string
description: 'List of JA4H HTTP client fingerprints observed in network traffic from the IP.
JA4H captures characteristics of HTTP client behavior including method,
headers, and cookie fields, useful for identifying and tracking HTTP clients.
'
example:
- ge11cn060000_4e59edc1297a_4da5efaf0cbd
Error:
type: object
properties:
message:
type: string
example: Success
required:
- message
responses:
ExceededLimit:
description: Too many requests. You've hit the rate-limit.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: You've hit the rate limit for this endpoint.
Unauthorized:
description: Unauthorized. Please check your API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Unauthorized
BadRequest:
description: 'Bad request - request syntax is invalid for the specified endpoint.
Verify request syntax and try again.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Invalid parameter
parameters:
query:
name: query
in: query
description: GNQL query string
required: true
schema:
type: string
example: tags:Mirai
securitySchemes:
APIKeyHeaderAuth:
type: apiKey
in: header
name: key
description: GreyNoise API key passed via the 'key' HTTP header.