Stories & Metadata v5 | Zignal Labs

Allows the retrieval of individual stories with meta-data for one or more Datasets, time range, optional sort order and a variety of filtering options.

Group and Issue filter options are limited to a maximum of 10 per filter. All other filter parameters that accept an array of terms are limited to a maximum of 50.

Each response is limited to 200 stories at a time. A ‘next’ token will be provided in the response that can be used to retrieve the next page of stories for the timeframe.

The response will contain the field potential_impressions if any impressions exist for the story, otherwise this field will be considered unknown and not included in the response.

gte cannot be more than 100 days in the past.
By default time is in UTC ‘Z’. It can be modified replacing ‘Z’ with time offsets that can go from ‘+12:00’ to ‘-12:00’: YYYY-MM-DDTHH:MM:SS±HH:MM.
Date values are optional. Default to the last 30 days when not specified.
Pagination: For a given date (timestamp) range, the ‘total’ field indicates the number of stories that fit the request. Of those results, 0 to 200 will be returned in the response. If the total exceeds the 200 limit, a ‘next’ token will be returned allowing the user to get the next block of results.
next is the token to retrieve the next page (if total results for request > 200).
sorted_by allows results to be retrieved in the order they were created (default) or in the order they were persisted in the Zignal platform. Possible values: persisted_at and created_at. If persisted_at is provided, only the last 2 days can be queried.

Allows the retrieval of individual stories with meta-data for one or more Datasets, time range, optional sort order and a variety of filtering options. Group and Issue filter options are limited to a maximum of 10 per filter. All other filter parameters that accept an array of terms are limited to a maximum of 50. Each response is limited to 200 stories at a time. A 'next' token will be provided in the response that can be used to retrieve the next page of stories for the timeframe. The response will contain the field `potential_impressions` if any impressions exist for the story, otherwise this field will be considered unknown and not included in the response. - `gte` cannot be more than 100 days in the past. - By default time is in UTC 'Z'. It can be modified replacing 'Z' with time offsets that can go from '+12:00' to '-12:00': `YYYY-MM-DDTHH:MM:SS±HH:MM`. - Date values are optional. Default to the last 30 days when not specified. - Pagination: For a given date (timestamp) range, the 'total' field indicates the number of stories that fit the request. Of those results, 0 to 200 will be returned in the response. If the total exceeds the 200 limit, a 'next' token will be returned allowing the user to get the next block of results. - `next` is the token to retrieve the next page (if total results for request > 200). - `sorted_by` allows results to be retrieved in the order they were created (default) or in the order they were persisted in the Zignal platform. Possible values: `persisted_at` and `created_at`. If `persisted_at` is provided, only the last 2 days can be queried.

Request

This endpoint expects an object.

profileslist of stringsRequired

Dataset (profile) IDs to query. Required. Must contain between 1 and 10 IDs.

gtestringOptional

Inclusive start date for time range. ISO 8601 Format: YYYY-MM-DDTHH:MM:SSZ

ltstringOptional

Exclusive end date for time range. ISO 8601 Format: YYYY-MM-DDTHH:MM:SSZ

keywordsobjectOptional

Filter stories by keyword presence.

entitiesobjectOptional

Filter by entities. Values must be prefixed with person:, place:, product:, or organization:.

groupslist of stringsOptional

Include stories matching these group IDs (max 10).

exclude_groupslist of stringsOptional

Exclude stories matching these group IDs (max 10).

issuesobjectOptional

Filter by issue IDs (max 10). Multiple IDs separated by ’|’.

sourcelist of objectsOptional

Filter by source type and optional subtypes.

threat_levelslist of integersOptional

Filter by threat level (0-4).

countrieslist of stringsOptional

Filter by country ISO codes (story location).

stateslist of stringsOptional

Filter by state codes (story location).

citieslist of stringsOptional

Filter by city codes (story location).

countries_referencelist of stringsOptional

Filter by country ISO codes (reference location).

states_referencelist of stringsOptional

Filter by state codes (reference location).

cities_referencelist of stringsOptional

Filter by city codes (reference location).

languageslist of stringsOptional

Filter by language ISO codes.

sentimentlist of stringsOptional

Filter by sentiment classification.

influenceobjectOptional

Filter by influence score range.

media_outletslist of stringsOptional

Filter by media outlet names.

domainslist of stringsOptional

Filter by link domains.

story_domainslist of stringsOptional

Filter by story domains.

link_or_story_domainslist of stringsOptional

Filter by link or story domains.

authorslist of stringsOptional

Filter by author names.

original_authorslist of stringsOptional

Filter by original author names.

any_authorlist of stringsOptional

Filter by any author field.

broadcast_dmalist of stringsOptional

Filter by broadcast DMA regions.

broadcast_station_namelist of stringsOptional

Filter by broadcast station names.

geo_distanceobjectOptional

Filter by geographic proximity (story location). Max 25mi or 40km.

geo_distance_referenceobjectOptional

Filter by geographic proximity (reference location). Max 25mi or 40km.

exclude_press_releasesbooleanOptional

Exclude press release stories from results.

automation_scoreobjectOptional

Filter by automation/bot score range.

contentlist of enumsOptional

Filter by content type.

Allowed values:

sorted_byenumOptional

Sort order field.

Allowed values:

orderenumOptional

Sort direction.

Allowed values:

smartFilterIdstringOptional

Smart Filter ID.

nextstringOptional

Pagination token for next set of stories.

Response

Successful response

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

Allows the retrieval of individual stories with meta-data for one or more Datasets, time range, optional sort order and a variety of filtering options.

Group and Issue filter options are limited to a maximum of 10 per filter. All other filter parameters that accept an array of terms are limited to a maximum of 50.

Each response is limited to 200 stories at a time. A ‘next’ token will be provided in the response that can be used to retrieve the next page of stories for the timeframe.

The response will contain the field potential_impressions if any impressions exist for the story, otherwise this field will be considered unknown and not included in the response.

gte cannot be more than 100 days in the past.
By default time is in UTC ‘Z’. It can be modified replacing ‘Z’ with time offsets that can go from ‘+12:00’ to ‘-12:00’: YYYY-MM-DDTHH:MM:SS±HH:MM.
Date values are optional. Default to the last 30 days when not specified.
Pagination: For a given date (timestamp) range, the ‘total’ field indicates the number of stories that fit the request. Of those results, 0 to 200 will be returned in the response. If the total exceeds the 200 limit, a ‘next’ token will be returned allowing the user to get the next block of results.
next is the token to retrieve the next page (if total results for request > 200).
sorted_by allows results to be retrieved in the order they were created (default) or in the order they were persisted in the Zignal platform. Possible values: persisted_at and created_at. If persisted_at is provided, only the last 2 days can be queried.

$	curl -X POST https://api.zignallabs.com/newsroom/v5/stories \
>	-H "Content-Type: application/json" \
>	-d '{
>	"profiles": [
>	"12345",
>	"67890"
>	],
>	"gte": "2026-05-11T00:00:00Z",
>	"lt": "2026-05-18T00:00:00Z",
>	"keywords": {
>	"mustinclude": [
>	"cybersecurity",
>	"breach"
>	],
>	"include": [
>	"ransomware"
>	],
>	"exclude": [
>	"test"
>	]
>	},
>	"entities": {
>	"mustinclude": [
>	"person:Johnny Appleseed",
>	"place:Narnia"
>	],
>	"include": [
>	"product:Holodeck"
>	],
>	"exclude": [
>	"organization:Acme Corporation"
>	]
>	},
>	"groups": [
>	"grp-001",
>	"grp-002"
>	],
>	"exclude_groups": [
>	"grp-003"
>	],
>	"source": [
>	{
>	"type": "news"
>	},
>	{
>	"type": "twitter",
>	"subtype": [
>	"reply",
>	"quote"
>	]
>	}
>	],
>	"threat_levels": [
>	3,
>	4
>	],
>	"countries": [
>	"US",
>	"GB"
>	],
>	"languages": [
>	"en",
>	"es"
>	],
>	"sentiment": [
>	"positive",
>	"negative"
>	],
>	"influence": {
>	"min": 50,
>	"max": 100,
>	"unknown": false
>	},
>	"sorted_by": "created_at",
>	"order": "desc"
>	}'