Monitoring Trending Stories

Looking to keep track of trending events currently being discussed across OSINT, Social, and Darkweb sources? You're in the right place.

First, get all listing of all current stories. Sort by 'reference_count' with a 24h created_after. Make sure to

Stories Index

get

Get paginated list of stories.

Stories are collections of related references that have been clustered together based on content similarity and temporal proximity.

Date filtering is handled by the StoryFilter via TimestampFilterMixin, using parameters like created_at__gte, created_at__lt, updated_at__gte, updated_at__lt.

Query parameters

filterstringOptional

A string used to filter stories. Allowed filter terms:

• title:: filter by title (case insensitive substring)
• description:: filter by description (case insensitive substring)
• min_refs:: filter by minimum reference count (e.g., min_refs:5)
• max_refs:: filter by maximum reference count (e.g., max_refs:10)
• topic:: filter by topic labels (comma-separated, OR logic, e.g., topic:ransomware,malware)
• If no prefix is provided, the filter will search in the title.

topicsstring[]Optional

Filter by topic labels. Pass multiple values for OR logic (e.g., topics=ransomware&topics=malware). This is an alternative to using filter=topic:....

Default: []

sortstringOptional

Field to sort by - either created_at, updated_at, title, or reference_count

Default: created_atPattern: ^(created_at|updated_at|title|reference_count)$

orderstringOptional

Sort order - either asc or desc

Default: descPattern: ^(asc|desc)$

offsetintegerOptional

The number of items to skip before starting to collect the result set.

Default: 0

limitinteger · min: 1 · max: 1000Optional

The maximum number of items to return.

Default: 100

followed_entitiesbooleanOptional

When true, returns only stories that mention entities the tenant is following

Default: false

followed_topicsbooleanOptionalDefault: false

created_at__gteany ofOptional

Filter on the created_at field for items greater than or equal to the given value

string · date-timeOptional

or

nullOptional

created_at__ltany ofOptional

Filter on the created_at field for items less than the given value

string · date-timeOptional

or

nullOptional

updated_at__gteany ofOptional

Filter on the updated_at field for items greater than or equal to the given value

string · date-timeOptional

or

nullOptional

updated_at__ltany ofOptional

Filter on the updated_at field for items less than the given value

string · date-timeOptional

or

nullOptional

Responses

200

Successful Response

application/json

404

Not found

422

Validation Error

application/json

get

/v1/stories

HTTPcURLJavaScriptPython

GET /v1/stories HTTP/1.1
Accept: */*

{
  "total": 1,
  "offset": 1,
  "limit": 1,
  "message": "text",
  "data": [
    {
      "uuid": "text",
      "title": "text",
      "description": "text",
      "image_s3_key": "text",
      "created_at": "2026-02-03T18:44:32.484Z",
      "updated_at": "2026-02-03T18:44:32.484Z",
      "enriched_at": "2026-02-03T18:44:32.484Z",
      "reference_count": 1,
      "references": [
        {
          "uuid": "text",
          "url": "text",
          "url_hash": "text",
          "type": "STRUCTURED",
          "source": "text",
          "created_at": "2026-02-03T18:44:32.484Z",
          "updated_at": "2026-02-03T18:44:32.484Z",
          "published_at": "2026-02-03T18:44:32.484Z",
          "first_collected_at": "2026-02-03T18:44:32.484Z",
          "last_collected_at": "2026-02-03T18:44:32.484Z",
          "screenshotted_at": "2026-02-03T18:44:32.484Z",
          "user_generated_content": true,
          "synthetic": true,
          "content_type": "text",
          "topic": "text",
          "authors": [
            "text"
          ],
          "content_chunk_uuids": [
            "text"
          ],
          "final_url": "text",
          "last_http_status": 1,
          "submitter": "text",
          "screenshot_url": "text"
        }
      ],
      "topic_labels": [
        "text"
      ]
    }
  ]
}

Next, using the UUID of the story, you can get the story, and supporting datapoints.

Single Story

get

Retrieve a story by its UUID.

• identifier: The unique UUID of the story to retrieve.

• include_merged: Set to true to include merged stories (default: false).

This endpoint returns the story object associated with the given UUID. If no story is found, a 404 error is returned.

Path parameters

identifierstringRequired

The unique UUID of the story to retrieve

Query parameters

include_mergedbooleanOptional

Include stories that have been merged into other stories

Default: false

Responses

200

Successful Response

application/json

404

Not found

422

Validation Error

application/json

get

/v1/stories/{identifier}

HTTPcURLJavaScriptPython

GET /v1/stories/{identifier} HTTP/1.1
Accept: */*

{
  "uuid": "text",
  "title": "text",
  "description": "text",
  "image_s3_key": "text",
  "created_at": "2026-02-03T18:44:32.484Z",
  "updated_at": "2026-02-03T18:44:32.484Z",
  "enriched_at": "2026-02-03T18:44:32.484Z",
  "reference_count": 1,
  "references": [
    {
      "uuid": "text",
      "url": "text",
      "url_hash": "text",
      "type": "STRUCTURED",
      "source": "text",
      "created_at": "2026-02-03T18:44:32.484Z",
      "updated_at": "2026-02-03T18:44:32.484Z",
      "published_at": "2026-02-03T18:44:32.484Z",
      "first_collected_at": "2026-02-03T18:44:32.484Z",
      "last_collected_at": "2026-02-03T18:44:32.484Z",
      "screenshotted_at": "2026-02-03T18:44:32.484Z",
      "user_generated_content": true,
      "synthetic": true,
      "content_type": "text",
      "topic": "text",
      "authors": [
        "text"
      ],
      "content_chunk_uuids": [
        "text"
      ],
      "final_url": "text",
      "last_http_status": 1,
      "submitter": "text",
      "screenshot_url": "text"
    }
  ],
  "topic_labels": [
    {
      "label": "text",
      "similarity_score": 1
    }
  ]
}

If you'd like to get additional detail, including related stories, and supporting events, use the following endpoints.

Story Events

get

Get timeline events for a specific story with pagination and sorting.

Returns a chronological list of events that have occurred for this story, such as creation and reference assignments. Events are sorted by created_at.

Path parameters

identifierstringRequired

The unique UUID of the story

Query parameters

filterstringOptional

Filter parameter (e.g., 'event_type:story_created', 'event_type:reference_assigned')

orderstringOptional

Sort order - either asc or desc

Default: descPattern: ^(asc|desc)$

offsetintegerOptional

The number of items to skip before starting to collect the result set.

Default: 0

limitinteger · min: 1 · max: 1000Optional

The maximum number of items to return.

Default: 100

Responses

200

Successful Response

application/json

404

Not found

422

Validation Error

application/json

get

/v1/stories/{identifier}/events

HTTPcURLJavaScriptPython

GET /v1/stories/{identifier}/events HTTP/1.1
Accept: */*

{
  "total": 1,
  "offset": 1,
  "limit": 1,
  "message": "text",
  "data": [
    {
      "uuid": "text",
      "story_uuid": "text",
      "event_type": "text",
      "created_at": "2026-02-03T18:44:32.484Z",
      "event_data": {
        "reference_uuid": "text"
      }
    }
  ]
}

Story References

get

Get references associated with a specific story with pagination and sorting.

Returns a list of references that have been clustered into this story.

Path parameters

identifierstringRequired

The unique UUID of the story

Query parameters

sortstringOptional

Field to sort by - either published_at, created_at, updated_at, title, or source_slug

Default: published_atPattern: ^(published_at|created_at|updated_at|title|source_slug)$

orderstringOptional

Sort order - either asc or desc

Default: descPattern: ^(asc|desc)$

offsetintegerOptional

The number of items to skip before starting to collect the result set.

Default: 0

limitinteger · min: 1 · max: 1000Optional

The maximum number of items to return.

Default: 100

Responses

200

Successful Response

application/json

404

Not found

422

Validation Error

application/json

get

/v1/stories/{identifier}/references

HTTPcURLJavaScriptPython

GET /v1/stories/{identifier}/references HTTP/1.1
Accept: */*

{
  "total": 1,
  "offset": 1,
  "limit": 1,
  "message": "text",
  "data": [
    {
      "uuid": "text",
      "url": "text",
      "url_hash": "text",
      "type": "STRUCTURED",
      "source": "text",
      "created_at": "2026-02-03T18:44:32.484Z",
      "updated_at": "2026-02-03T18:44:32.484Z",
      "published_at": "2026-02-03T18:44:32.484Z",
      "first_collected_at": "2026-02-03T18:44:32.484Z",
      "last_collected_at": "2026-02-03T18:44:32.484Z",
      "screenshotted_at": "2026-02-03T18:44:32.484Z",
      "user_generated_content": true,
      "synthetic": true,
      "content_type": "text",
      "topic": "text",
      "authors": [
        "text"
      ],
      "content_chunk_uuids": [
        "text"
      ],
      "final_url": "text",
      "last_http_status": 1,
      "submitter": "text",
      "screenshot_url": "text"
    }
  ]
}

Similar Stories

get

Find stories similar to the specified story.

Uses the story's embedding vector to find other stories with similar content using inner product similarity. Results are ordered by similarity (most similar first).

Date filters use created_at__gte/lt and updated_at__gte/lt query parameters.

Returns an empty list if the story doesn't have an embedding vector.

Path parameters

identifierstringRequired

The unique UUID of the story

Query parameters

thresholdnumber · min: -1 · max: 1Optional

Similarity threshold (higher values are more similar, range: -1 to 1)

Default: 0.6

offsetintegerOptional

The number of items to skip before starting to collect the result set.

Default: 0

limitinteger · min: 1 · max: 100Optional

The maximum number of items to return.

Default: 10

created_at__gteany ofOptional

Filter on the created_at field for items greater than or equal to the given value

string · date-timeOptional

or

nullOptional

created_at__ltany ofOptional

Filter on the created_at field for items less than the given value

string · date-timeOptional

or

nullOptional

updated_at__gteany ofOptional

Filter on the updated_at field for items greater than or equal to the given value

string · date-timeOptional

or

nullOptional

updated_at__ltany ofOptional

Filter on the updated_at field for items less than the given value

string · date-timeOptional

or

nullOptional

Responses

200

Successful Response

application/json

404

Not found

422

Validation Error

application/json

get

/v1/stories/{identifier}/similar

HTTPcURLJavaScriptPython

GET /v1/stories/{identifier}/similar HTTP/1.1
Accept: */*

{
  "total": 1,
  "offset": 1,
  "limit": 1,
  "message": "text",
  "data": [
    {
      "uuid": "text",
      "title": "text",
      "description": "text",
      "image_s3_key": "text",
      "created_at": "2026-02-03T18:44:32.484Z",
      "updated_at": "2026-02-03T18:44:32.484Z",
      "enriched_at": "2026-02-03T18:44:32.484Z",
      "reference_count": 1,
      "references": [
        {
          "uuid": "text",
          "url": "text",
          "url_hash": "text",
          "type": "STRUCTURED",
          "source": "text",
          "created_at": "2026-02-03T18:44:32.484Z",
          "updated_at": "2026-02-03T18:44:32.484Z",
          "published_at": "2026-02-03T18:44:32.484Z",
          "first_collected_at": "2026-02-03T18:44:32.484Z",
          "last_collected_at": "2026-02-03T18:44:32.484Z",
          "screenshotted_at": "2026-02-03T18:44:32.484Z",
          "user_generated_content": true,
          "synthetic": true,
          "content_type": "text",
          "topic": "text",
          "authors": [
            "text"
          ],
          "content_chunk_uuids": [
            "text"
          ],
          "final_url": "text",
          "last_http_status": 1,
          "submitter": "text",
          "screenshot_url": "text"
        }
      ],
      "topic_labels": [
        "text"
      ]
    }
  ]
}