Get Tag Activity

get

https://api.greynoise.io/v3/tags/{id}/activity

Retrieve a single tag's activity over time as a series of time buckets, each
reporting how many distinct IP addresses were seen scanning for that tag.

The series is returned under activity, keyed by the tag's intention
(for example malicious). Buckets are contiguous and half-open: a bucket
covers start inclusive to end exclusive. Buckets with no activity are
still returned, with active_ips of 0.

Set include_ips=true to additionally receive the IP addresses behind each
bucket. This is opt-in because it is substantially more expensive than the
counts alone, and the per-bucket list is capped — see ips_truncated below.

Path Params

uuid

required

The UUID of the tag, as returned in the id field of GET /v3/tags.

Must be a well-formed UUID. A malformed value returns 400.

Query Params

days

integer

1 to 90

Defaults to 1

How many days back to retrieve activity for.

The requested value is additionally clamped by the data reach granted to
your workspace by your plan. If you ask for more days than your plan
allows, the request succeeds against the shorter window rather than
failing — check metadata.start_date to see the window actually used.

granularity

string

Defaults to 24h

The width of each time bucket, as a duration string.

Specify the width in whole hours with the h suffix, such as 1h, 4h,
24h or 168h. The duration must be between 1 hour and 1 week
(168h) inclusive; anything outside that range returns 400.

include_ips

boolean

Defaults to false

When true, each bucket additionally carries the ips array of distinct
source IP addresses observed in that bucket, and metadata reports
ips_included, ips_per_bucket and ips_truncated.

Defaults to false. Values are parsed as booleans (true/false, 1/0);
any other value returns 400 before the query runs.

Requesting IPs is significantly slower than requesting counts alone, and
each bucket's list is capped at 1,000 addresses. Prefer leaving this off
when you only need the activity counts.

workspace_labels

string

Comma-separated list of dataset scopes to include in the query.
When omitted, only the default GreyNoise global dataset is queried.

Allowed values:

greynoise: GreyNoise's global dataset.
community: Aggregated community-contributed data.
personal: The authenticated caller's own workspace data.
Requires an authenticated workspace.

Enforcement varies by endpoint; see each operation's response codes:

GET /v3/ip/{ip} and POST /v3/ip return 403 Forbidden when any
value is supplied without the Community Dataset entitlement. Values
are not validated server-side; unrecognized values yield empty
results rather than an error.
GET /v3/noise/ips/{ip}/timeline returns 400 Bad Request for
unrecognized values and for personal without an authenticated
workspace. The Community Dataset entitlement is not enforced on
this endpoint.
GET /v3/tags/{id}/activity returns 400 Bad Request for unrecognized
values, and 403 Forbidden for recognized values supplied without the
Community Dataset entitlement.

Responses

200OK - request successful.

400Bad request - request syntax is invalid for the specified endpoint. Verify request syntax and try again.

401Unauthorized. Please check your API key.

403Forbidden - request is not authorized due to an invalid API key or plan limitations. If due to plan limitations, contact [email protected] to upgrade your plan and unlock full results.

404Resource not found.

429Too many requests. You've hit the rate-limit.

500Unexpected error