List

Description

Retrieve a list of stories.

Request

HTTP Method: GET

Query Parameter Description
team_id Optional Return stories belonging to this team.
folder_id Optional Return stories in this folder.
per_page Optional Set the number of results returned per page.
page Optional Specify the page of results to return if there are multiple pages. Defaults to page 1.
tags Optional An array of tag names to filter by
search Optional A string that searches against story name
filter Optional Filter by one of: SEND_TO_STORY_ENABLED, HIGH_PRIORITY, API_ENABLED, PUBLISHED (deprecated), FAVORITE, CHANGE_CONTROL_ENABLED, DISABLED, LOCKED
order Optional Order the results by one of: NAME, NAME_DESC, RECENTLY_EDITED, LEAST_RECENTLY_EDITED, ACTION_COUNT_ASC, ACTION_COUNT_DESC
include_live_activity Optional When set to true, includes live activity metrics like pending_action_runs_count, concurrent_runs_count, and tokens_used_percentage. Defaults to false. 
curl -X GET \
  https://<<META.tenant.domain>>/api/v1/stories?include_live_activity=true \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

Response

A successful request will return a JSON Array describing stories in the Tines tenant.

Field description

Parameter Description
name The story name.
user_id ID of story creator.
description A user-defined description of the story.
keep_events_for Defined event retention period in seconds.
disabled Boolean flag indicating whether story is disabled.
priority Boolean flag indicating whether story is high priority story.
send_to_story_enabled Boolean flag indicating if Send to Story is enabled.
send_to_story_access_source STS, STS_AND_WORKBENCH, WORKBENCH or OFF indicating where the send to story can be used.
send_to_story_access Controls who is allowed to send to this story (TEAM,GLOBAL,SPECIFIC_TEAMS).
shared_team_slugs List of teams' slugs that can send to this story when send_to_story_access is SPECIFIC_TEAMS, otherwise empty.
send_to_story_skill_use_requires_confirmation Boolean flag indicating whether workbench should ask for confirmation before running this story.
entry_agent_id The ID of the entry action for this story.
exit_agents An Array of objects describing exit actions for this story.
team_id ID of team to which the story belongs.
tags An array of tags used to classify the story.
guid Unique identifier of the story.
slug An underscored representation of the story name.
created_at ISO 8601 Timestamp representing date and time the story was created.
updated_at ISO 8601 Timestamp representing date and time the story row was last updated. It is best to use edited_at to track any modifications made to the story itself.
edited_at ISO 8601 Timestamp representing date and time the story was last logically updated.
mode The mode of the story. Only LIVE stories will be listed.
id The story ID.
folder_id ID of folder to which the story belongs.
published Boolean flag indicating whether the story is published.
change_control_enabled Boolean flag indicating if change control is enabled.
locked Boolean flag indicating whether the story is locked to changes.
owners List of user IDs that are listed as owners on the story.
monitor_failures Boolean flag indicating if monitor failures is enabled on all actions in the story. This will be false when only some actions have monitoring enabled.
actions_with_monitoring List of action IDs with monitoring enabled.
recipients List of monitoring recipients for the story.
pending_action_runs_count Total number of pending action runs across all actions in the story. Only included when include_live_activity=true is set.
concurrent_runs_count Number of concurrent story runs currently executing. Only included when include_live_activity=true is set.
tokens_used_percentage Percentage of token limit used by the story. Only included when include_live_activity=true is set.

Sample response

{
  "stories": [
    {
      "name": "Simple story",
      "user_id": 167,
      "description": "In the simple story we will create a fictional situation where a detection system is configured to send alerts to our Tines tenant",
      "keep_events_for": 604800,
      "disabled": false,
      "priority": false,
      "send_to_story_enabled": false,
      "send_to_story_access_source": "OFF",
      "send_to_story_access": null,
      "send_to_story_skill_use_requires_confirmation": true,
      "shared_team_slugs": [],
      "entry_agent_id": null,
      "exit_agents": [],
      "team_id": 1,
      "tags": ["Tag 1", "Tag 2"],
      "guid": "df1e838a18d20696120b41516497b017",
      "slug": "simple_story",
      "created_at": "2021-05-10T08:56:50Z",
      "updated_at": "2021-05-10T08:56:50Z",
      "edited_at": "2021-05-10T08:56:50Z",
      "mode": "LIVE",
      "id": 7981,
      "folder_id": 1,
      "published": true,
      "change_control_enabled": false,
      "locked": false,
      "owners": [1],
      "monitor_failures": false,
      "actions_with_monitoring": [],
      "recipients": [
        {
          "address": "test@example.com"
        }
      ],
      "pending_action_runs_count": 150,
      "concurrent_runs_count": 3,
      "tokens_used_percentage": 15.7
    }
  ],
  "meta": {
    "current_page": "https://<<META.tenant.domain>>/api/v1/stories?per_page=20&page=1",
    "previous_page": null,
    "next_page": null,
    "next_page_number": null,
    "per_page": 20, // Max: 500
    "pages": 1,
    "count": 1
  }
}
Was this helpful?