Retrieve Multiple Stories

Retrieve multiple stories from Storyblok with filtering, pagination, sorting, and relation resolution options.

GET

https://api.storyblok.com/v2/cdn/stories

Query parameters

version string
Filter by the story’s publication status.
cv integer
Cached version Unix timestamp. Learn more in the Caching concept.
starts_with string
Filter by the story’s full_slug to return items starting with the given value.
search_term string
Search for any string in stories. The response contains all stories where the string appears anywhere in the name, slug, full slug, or content object. This includes UUIDs, field values, asset file names, and rich text nodes and attributes, such as “bold”. Combine this parameter with the version parameter to filter by draft or published stories.
sort_by string
Sort stories in ascending or descending order by a specific property. Possible properties are all default story properties and any custom fields defined in the schema of the story type.
Sort default story properties like so:
- sort_by=created_at:desc
- sort_by=slug:asc
Sort custom fields can like so:
- sort_by=content.meta_description:asc
- sort_by=content.event_title:desc
By default, all sorted custom fields are strings. To sort custom fields with numeric values, specify floats or integers:
- sort_by=content.price:asc:float
- sort_by=content.event_number:asc:int
Chain different sorts with commas: sort_by=name:desc,slug:asc.
Sort values and set the null or empty ones first or last:
- sort_by=path:desc:nulls_first
- sort_by=path:desc:nulls_last.
nulls_last is the default behavior. Examples: created_at:desc (Sort by date), content.meta_description:asc (Sort by Content Metadata), name:desc,slug:asc (Sort by chaining with commas), path:desc:nulls_first (Sort by keeping null first).
per_page integer
The number of items per page in a paginated response.
page integer
Page number in a paginated response.
by_slugs string
Retrieve stories by comma-separated full_slug. For example, by_slugs=posts/third-post,posts/second-post.
You can use * as a wildcard. For example, by_slugs=posts/*. Examples: posts/my-third-post,posts/my-second-post (Two explicit slugs), posts/* (Wildcard prefix).
excluding_slugs string
Exclude stories by comma-separated full_slug. For example, excluding_slugs=posts/third-post,posts/second-post.
You can use * as a wildcard. For example, excluding_slugs=posts*.
published_at_gt string
Retrieve stories published after the specified date. Supports ISO 8601.
published_at_gte string
Retrieve stories published on or after the specified date. Supports ISO 8601.
published_at_lt string
Retrieve stories published before the specified date. Supports ISO 8601.
published_at_lte string
Retrieve stories published on or before the specified date. Supports ISO 8601.
first_published_at_gt string
Retrieve stories first published after the specified date. Supports ISO 8601.
first_published_at_gte string
Retrieve stories first published at or after the specified date. Supports ISO 8601.
first_published_at_lt string
Retrieve stories first published before the specified date Supports ISO 8601.
first_published_at_lte string
Retrieve stories first published at or before the specified date. Supports ISO 8601.
updated_at_gt string
Retrieve stories updated after the specified date. Supports ISO 8601.
updated_at_gte string
Retrieve stories updated at or after the specified date. Supports ISO 8601.
updated_at_lt string
Retrieve stories updated before the specified date. Supports ISO 8601.
updated_at_lte string
Retrieve stories updated at or before the specified date. Supports ISO 8601.
in_workflow_stages string
Retrieve stories in a particular workflow stage by providing a comma-separated list of workflow stage IDs. For example, in_workflow_stages=325604,325605.
content_type string
Retrieve stories of a specific content type block. For example, content_type=page.
level integer
Retrieve stories in the specified folder level. Examples:
- level=1 retrieves stories from the root folder
- level=2 retrieves stories from top-level folders
- level=3 retrieves stories from second-level folders
The response includes only the immediate child stories, excluding stories defined as root for the folder. Examples: 1 (retrieves stories from the root folder), 2 (retrieves stories from top-level folders), 3 (retrieves stories from second-level folders).
resolve_relations string
Used to resolve referenced stories. Resolved stories appear in the rels property of the response.
A single request can resolve up to 50 stories. Afterward, all story UUID appear in the rel_uuids property of the response and need to resolve in subsequent API requests.
To resolve the stories selected in one field, provide the technical name of the immediate parent component of the field, followed by a . and the field name. To resolve the stories selected in multiple fields, provide a comma-separated string.
Example: resolve_relations=page.author,page.categories.
excluding_ids string
Exclude specific stories by IDs in a comma-separated string. For example, excluding_ids=335015953,335015954.
by_uuids string
Retrieve specific stories by UUIDs in a comma-separated string. For example, by_uuids=a78b2116-c26d-4d23-9cbe-fec477847b0e,9683820e-fc17-429e-ba23-eb41f26c0776.
by_uuids_ordered string
Retrieve specific stories by UUIDs in a comma-separated string. The order of the stories in the response matches the order of the UUIDs. For example, by_uuids_ordered=a78b2116-c26d-4d23-9cbe-fec477847b0e,9683820e-fc17-429e-ba23-eb41f26c0776.
by_ids string
Retrieve items by id. Supports a comma-separated string.
with_tag string
Filter by specific tag slug. For example, with_tag=featured.
Filter multiple tags by comma-separated string (treated like an OR operator). For example, with_tag=featured,editors_choice. Examples: featured (single tag), featured,editors_choice (multiple tags).
is_startpage integer
Filter by stories defined as root for the folder. Examples: 1 (Only root stories), 0 (Exclude root stories).
resolve_links string
Resolve link fields. The links property of the response includes resolved links:
- link: provides access to additional information, such as a linked story’s full_slug, path, parent_id, is_folder, published, is_startpage, position, alternates, real_path, and more.
- url: provides the minimum amount of information. Use when you only need the path of a linked story.
- story: resolves and returns the complete story object of a linked story.
resolve_links_level integer
Resolve up to two levels of links.
from_release string
Access a story version in a specific release by providing the release ID.
fallback_lang string
Define a custom fallback language to handle untranslated fields. Accepts any language code configured in the space. Provide language code with underscores. For example, es_co instead of es-co.
language string
Retrieve translated story version. Accepts any language code configured in the Storyblok space.
filter_query object
Learn more in Filter Queries. Examples: \{"role":\{"in_array":["marketer","developer"]\}\} (Array form), \{"role":\{"in_array":"marketer,developer"\}\} (CSV form), \{"options":\{"all_in_array":["red"]\}\} (all_in_array), \{"options":\{"exists":"red"\}\} (exists), \{"nested.lng":\{"gt_float":2.5\}\} (gt_float), \{"__or":[\{"headline":\{"in":"tom"\}\},\{"component":\{"in":"news"\}\}]\} (__or).
excluding_fields string
To exclude specific fields of a content type, provide the field names as a comma-separated string. For example, excluding_fields=body,meta_description.
Excluding the component field from the response, returns the content of the story in the default language instead of the requested language.
excluding_story_fields string
Exclude top-level story response fields with a comma-separated list. For example, excluding_story_fields=alternates,translated_slugs.
resolve_assets integer
Used to resolve asset metadata, including custom metadata. When resolve_assets=1, an array of assets associated with the stories appear in the assets property of the response.
resolve_level integer
Used to force resolve second-level relations when the first level reaches a limit of 100 relations.
While resolving relations, if the first level exceeds 100 relations, the API stops looking for the second level. To resolve second-level relations regardless of the first-level relations’ limit, use resolve_level=2.
only_variants string
When set, returns only experiment variant stories.
token required string
A preview or public access token configured in a space.

Response properties

stories array<Story>
An array of story objects.
Show child properties
- name string
  Story name.
- created_at string
  Creation timestamp. Supports ISO 8601.
- updated_at string | null
  Latest update timestamp. Supports ISO 8601.
- published_at string | null
  Latest publication timestamp. Supports ISO 8601.
- alternates array<StoryAlternate>
  An array that contains objects that provide basic data of the stories defined as alternates of the current story.
  Show child properties
  id integer
  Story ID.
  name string
  Story name.
  slug string
  Story slug.
  published boolean | null
  Returns true if the story is currently published.
  full_slug string
  The story’s full slug, including parent folder and language paths.
  is_folder boolean
  Returns true if the item is a folder.
  parent_id integer
  ID of the parent folder.
- id integer
  Story ID.
- uuid string
  Story UUID.
- content object
  An object that contains the field data associated with a content type’s specific structure. Also includes a component property with the content type’s technical name.
  Show child properties
  _uid string
  component string
- slug string
  Story.
- full_slug string
  The story’s full slug, including parent folder and language paths.
- default_full_slug string | null
  Contains the complete slug of the default language (requires the Translatable Slugs app).
- sort_by_date string | null
  Date defined in the story’s entry configuration. Supports ISO 8601.
- position integer
  Numeric representation of the story’s position in the folder. Users can change this property in the Content tab.
- tag_list array<string>
  An array of tags.
- is_startpage boolean
  Returns true if the story is the folder root.
- parent_id integer
  Parent folder ID.
- meta_data object | null
  An object to store non-editable data that’s exclusively maintained with the Management API.
- group_id string
  Group ID (UUID string), shared between stories defined as alternates.
- first_published_at string | null
  First publication timestamp. Supports ISO 8601.
- release_id integer | null
  Current release ID (if requested via the from_release parameter).
- lang string
  The story’s language code.
- path string | null
  Real path defined in the story’s entry configuration. Learn more in the Visual Editor concept).
- translated_slugs array | null
  An array of translated slug objects (requires the Translatable Slugs app).
  Show child properties
  path string
  Translated slug.
  name string | null
  Translated name.
  lang string
  The story’s language code.
  published boolean | null
  Returns true if story variant is currently published.
- taxonomy_terms array<object>
  To retrieve taxonomy terms assigned to the story, use with_taxonomy_terms=1.
  Show child properties
  id string
  display_name string
  name string
  taxonomy_id string
cv integer
Cache version.
rels array<Story>
An array of resolved stories.
Show child properties
- name string
  Story name.
- created_at string
  Creation timestamp. Supports ISO 8601.
- updated_at string | null
  Latest update timestamp. Supports ISO 8601.
- published_at string | null
  Latest publication timestamp. Supports ISO 8601.
- alternates array<StoryAlternate>
  An array that contains objects that provide basic data of the stories defined as alternates of the current story.
  Show child properties
  id integer
  Story ID.
  name string
  Story name.
  slug string
  Story slug.
  published boolean | null
  Returns true if the story is currently published.
  full_slug string
  The story’s full slug, including parent folder and language paths.
  is_folder boolean
  Returns true if the item is a folder.
  parent_id integer
  ID of the parent folder.
- id integer
  Story ID.
- uuid string
  Story UUID.
- content object
  An object that contains the field data associated with a content type’s specific structure. Also includes a component property with the content type’s technical name.
  Show child properties
  _uid string
  component string
- slug string
  Story.
- full_slug string
  The story’s full slug, including parent folder and language paths.
- default_full_slug string | null
  Contains the complete slug of the default language (requires the Translatable Slugs app).
- sort_by_date string | null
  Date defined in the story’s entry configuration. Supports ISO 8601.
- position integer
  Numeric representation of the story’s position in the folder. Users can change this property in the Content tab.
- tag_list array<string>
  An array of tags.
- is_startpage boolean
  Returns true if the story is the folder root.
- parent_id integer
  Parent folder ID.
- meta_data object | null
  An object to store non-editable data that’s exclusively maintained with the Management API.
- group_id string
  Group ID (UUID string), shared between stories defined as alternates.
- first_published_at string | null
  First publication timestamp. Supports ISO 8601.
- release_id integer | null
  Current release ID (if requested via the from_release parameter).
- lang string
  The story’s language code.
- path string | null
  Real path defined in the story’s entry configuration. Learn more in the Visual Editor concept).
- translated_slugs array | null
  An array of translated slug objects (requires the Translatable Slugs app).
  Show child properties
  path string
  Translated slug.
  name string | null
  Translated name.
  lang string
  The story’s language code.
  published boolean | null
  Returns true if story variant is currently published.
- taxonomy_terms array<object>
  To retrieve taxonomy terms assigned to the story, use with_taxonomy_terms=1.
  Show child properties
  id string
  display_name string
  name string
  taxonomy_id string
links array<LinkWithFullSlug>
An array of resolved links.
Show child properties
- id integer
  Story or folder id.
- uuid string
  Story or folder uuid.
- slug string
  Story or folder full slug.
- path string | null
  Real path defined in the story’s entry configuration. Learn more in the Visual Editor concept).
- real_path string | null
  Either the full slug of the story or folder with a leading /, or the value of the real path defined in the story’s entry configuration with a leading /.
- name string
  Story or folder name.
- published boolean
  Returns true if the story is currently published.
- parent_id integer
  Parent folder ID.
- is_folder boolean
  Returns true if the item is a folder.
- is_startpage boolean
  Returns true if the story is the folder’s root.
- position integer
  Numeric representation of the story’s position in the folder. Users can change this property in the Content tab.
- published_at string | null
  Latest publication timestamp. Supports ISO 8601.
- created_at string | null
  Creation timestamp. Supports ISO 8601.
- updated_at string | null
  Latest update timestamp. Supports ISO 8601.
- alternates array<Alternate>
  An array that contains objects correlating to the language versions defined using field-level translation.
  The alternates parameter is different from the story alternates defined in the Dimensions app when using folder-level translation.
  Show child properties
  path string
  Translated story slug (learn more about the Translatable Slugs app).
  name string
  Translated story name (learn more about the Translatable Slugs app).
  lang string
  The story’s language code.
  published boolean
  Returns true if story language version is currently published.
  translated_slug string
  Translated story slug (learn more about the Translatable Slugs app).
- full_slug string
  The story’s full slug, including parent folder and language paths.
rel_uuids array<string>
An array of all referenced stories’ UUIDs.
link_uuids array<string>
An array of all linked stories’ UUIDs.

Examples

curl "https://api.storyblok.com/v2/cdn/stories\
?version=published\
&starts_with=articles\
&token=YOUR_ACCESS_TOKEN"

// storyblok-js-client@>=7, node@>=18
import Storyblok from "storyblok-js-client";

const storyblok = new Storyblok({
  accessToken: "krcV6QGxWORpYLUWt12xKQtt",
});

try {
  const response = await storyblok.get('cdn/stories', {
    "version": "published",
    "starts_with": "articles"
  })
  console.log({ response })
} catch (error) {
  console.log(error)
}

$client = new \Storyblok\Client('YOUR_STORYBLOK_SPACE_ACCESS_TOKEN');

$client->getStories([
  "version" => "published",
  "starts_with" => "articles"
])->getBody();

HttpResponse<String> response = Unirest.get("https://api.storyblok.com/v2/cdn/stories?version=published&starts_with=articles&token=YOUR_ACCESS_TOKEN")
  .asString();

var client = new RestClient("https://api.storyblok.com/v2/cdn/stories?version=published&starts_with=articles&token=YOUR_ACCESS_TOKEN");
var request = new RestRequest(Method.GET);

IRestResponse response = client.Execute(request);

import requests

url = "https://api.storyblok.com/v2/cdn/stories"

querystring = {"version":"published","starts_with":"articles","token":"YOUR_ACCESS_TOKEN"}

payload = ""
headers = {}

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

require 'storyblok'
client = Storyblok::Client.new(token: 'YOUR_TOKEN')

client.stories({:params => {
  "version" => "published",
  "starts_with" => "articles"
}})

let storyblok = URLSession(storyblok: .cdn(accessToken: "YOUR_ACCESS_TOKEN"))
var request = URLRequest(storyblok: storyblok, path: "stories")
request.url!.append(queryItems: [
    URLQueryItem(name: "version", value: "published"),
    URLQueryItem(name: "starts_with", value: "articles")
])
let (data, _) = try await storyblok.data(for: request)
print(try JSONSerialization.jsonObject(with: data))

val client = HttpClient {
    install(Storyblok(CDN)) {
        accessToken = "YOUR_ACCESS_TOKEN"
    }
}

val response = client.get("stories") {
    url {
        parameters.append("version", "published")
        parameters.append("starts_with", "articles")
    }
}

println(response.body<JsonElement>())

{
"stories": [
  {
    "name": "Homepage",
    "created_at": "2025-01-15T09:30:00.000Z",
    "updated_at": "2025-06-02T14:12:05.000Z",
    "published_at": "2025-01-15T09:32:10.000Z",
    "id": 371891025,
    "uuid": "8f14e45f-ceea-467e-adc1-5c1b1a3a7b3b",
    "content": {
      "_uid": "b1f8c9a2-3d44-4c2e-9a1e-6e7d2f5c9a10",
      "component": "page",
      "body": [
        {
          "_uid": "1a2b3c4d-5e6f-4a1b-8c2d-9e0f1a2b3c4d",
          "component": "teaser",
          "headline": "Welcome to Storyblok"
        }
      ]
    },
    "slug": "home",
    "full_slug": "home",
    "sort_by_date": null,
    "position": 0,
    "tag_list": [
      "marketing",
      "featured"
    ],
    "is_startpage": true,
    "parent_id": 0,
    "meta_data": null,
    "group_id": "57350688-5a28-49d1-b5a9-086ae0d4c0d2",
    "first_published_at": "2025-01-15T09:32:10.000Z",
    "release_id": null,
    "lang": "default",
    "path": null,
    "alternates": [],
    "default_full_slug": null,
    "translated_slugs": null
  },
  {
    "name": "Blog: Announcing our Q2 release",
    "created_at": "2025-04-02T11:05:00.000Z",
    "updated_at": "2025-04-02T11:20:00.000Z",
    "published_at": "2025-04-02T11:20:00.000Z",
    "id": 371891412,
    "uuid": "2c6b9a4a-2b9c-4d3f-9e21-2a6b6a2f0b3d",
    "content": {
      "_uid": "d2a9c1b0-4e55-4d3f-8b2a-7f6d3e5c9b21",
      "component": "blog_post",
      "headline": "Announcing our Q2 release"
    },
    "slug": "announcing-our-q2-release",
    "full_slug": "blog/announcing-our-q2-release",
    "sort_by_date": null,
    "position": 1,
    "tag_list": [
      "product-updates"
    ],
    "is_startpage": false,
    "parent_id": 371890998,
    "meta_data": null,
    "group_id": "9d1a6c3e-1f2b-4a5d-9c3e-6a2b1d4f0e7a",
    "first_published_at": "2025-04-02T11:20:00.000Z",
    "release_id": null,
    "lang": "default",
    "path": null,
    "alternates": [],
    "default_full_slug": null,
    "translated_slugs": null
  }
],
"cv": 1717516800
}

Was this page helpful?

This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window).Terms of Service (opens in a new window) apply.

Get in touch with the Storyblok community

Cookie notice

Retrieve Multiple Stories

Query parameters

Response properties

Examples