--- title: Retrieve Multiple Stories description: Retrieve multiple stories from Storyblok using the Content Delivery API with filtering, pagination, sorting, and relation resolution options. url: https://storyblok.com/docs/api/content-delivery/v2/stories/retrieve-multiple-stories --- # Retrieve Multiple Stories Returns an array of all stories (as [story objects](/docs/api/content-delivery/v2/stories/the-story-object)). The API response can be filtered using the query parameters, including specific [filter queries](/docs/api/content-delivery/v2/filter-queries/). GET ```html https://api.storyblok.com/v2/cdn/stories ``` > [!NOTE] > This endpoint is paginated by default, including a maximum of 100 stories in the response. See [Pagination](/docs/api/content-delivery/v2/getting-started/pagination) for further information. > [!TIP] > An empty array rather than a `404` error is returned if no stories are found with the filters applied. ## Query parameters - `token` (required) (string) A preview or public [access token](/docs/concepts/access-tokens) - `version` (draft | published) Default: `published` - `cv` (number) Cached version Unix timestamp (see [Cache Invalidation](/docs/api/content-delivery/v2/getting-started/cache-invalidation)) - `starts_with` (string) Filter by `full_slug` to only return stories starting with the given value, for example: `starts_with=blog/posts` - `from_release` (string) Access a story version in a specific release by providing the release ID - `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 (including UIDs, 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. - `per_page` (number) Default: `25`, Max: `100` (see [Pagination](/docs/api/content-delivery/v2/getting-started/pagination)) - `page` (number) Default: `1` (see [Pagination](/docs/api/content-delivery/v2/getting-started/pagination)) - `resolve_links` (story | url | link) Resolve [link fields](/docs/concepts/fields#link). Resolved links are included in the `links` property of the response. - `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`: If only the path of a linked story is required, this value provides the minimum amount of information. - `story`: Resolves and returns the complete story object of a linked story. - `resolve_links_level` (1 | 2) Default: `1`. Resolve up to two levels of links. - `resolve_relations` (string) Used to resolve [referenced stories](/docs/concepts/references). Resolved stories are included in the `rels` property of the response. Entries can be resolved two levels deep. A maximum of `50` stories can be resolved in a single request. If this limit is exceeded, _all_ story UUIDs are included in the `rel_uuids` property of the response and need to be resolved 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 list. Example: `resolve_relations=page.author,page.categories` - `resolve_level` (2) 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, by default, stops looking for the second level. Using `resolve_level=2`, second-level relations can be resolved even when the limit of first-level relations is reached. - `resolve_assets` (number) Used to resolve asset metadata, including custom metadata. When `resolve_assets=1`, an array of all assets associated with stories appear in the `assets` property of the response. - `fallback_lang` (string) Define a custom fallback language to handle untranslated fields. Accepts any language code that is configured in the Storyblok space. Note that the language code needs to be provided with underscores, even if it is defined with hyphens. For example, `es_co` instead of `es-co`. - `language` (string) Retrieve translated story version. Accepts any language code that is configured in the Storyblok space. - `content_type` (string) Retrieve stories of a specific content type. Example: `content_type=page` - `by_slugs` (string) Retrieve stories by comma-separated `full_slug`. Use wildcards by using `*`. Examples: - `by_slugs=posts/my-third-post,posts/my-second-post` - `by_slugs=posts/*` - `excluding_slugs` (string) Exclude stories by comma-separated `full_slug`. Use wildcards by using `*`. Examples: - `excluding_slugs=posts/my-third-post,posts/my-second-post` - `excluding_slugs=posts*` - `by_uuids` (string) Retrieve specific stories by providing their UUIDs as a comma-separated string. Example: `by_uuids=a78b2116-c26d-4d23-9cbe-fec477847b0e,9683820e-fc17-429e-ba23-eb41f26c0776` - `by_uuids_ordered` (string) Retrieve specific stories by providing their UUIDs as a comma-separated string. The order of the stories in the response matches the order in which the UUIDs are listed. Example: `by_uuids_ordered=a78b2116-c26d-4d23-9cbe-fec477847b0e,9683820e-fc17-429e-ba23-eb41f26c0776` - `excluding_ids` (string) Exclude specific stories by providing their IDs as a comma-separated string. Example: `excluding_ids=335015953,335015954` - `with_tag` (string) Filter by specific tag(s) by providing their slug(s). Multiple tags can be provided as a comma-separated string (treated like an OR operator). Examples: - `with_tag=featured` - `with_tag=featured,editors_choice` - `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. Default story properties can be sorted like this: - `sort_by=created_at:desc` - `sort_by=slug:asc` Custom fields can be sorted like this: - `sort_by=content.meta_description:asc` - `sort_by=content.event_title:desc` By default, all custom fields are sorted as strings. To sort custom fields with numeric values, specify whether they should be treated as float or integer. Examples: - `sort_by=content.price:asc:float` - `sort_by=content.event_number:asc:int` Different sorts can be chained using commas: `sort_by=name:desc,slug:asc` It is also possible to sort values keeping 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. - `in_workflow_stages` (string) Retrieve stories that are in a particular workflow stage by providing a comma-separated list of workflow stage IDs. Example: `in_workflow_stages=325604,325605` - `filter_query` (string) See [Filter Queries](/docs/api/content-delivery/v2/filter-queries/). - `level` (number) Retrieve stories located 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 Only the immediate child stories are included in the response. Stories defined as root for the folder are excluded. - `is_startpage` (0 | 1) Filter by stories defined as root for the folder. - `first_published_at_gt` (string) Retrieve stories _first_ published after the specified date (Formats: `yyyy-MM-dd HH:mm` or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format) - `first_published_at_lt` (string) Retrieve stories _first_ published before the specified date (Formats: `yyyy-MM-dd HH:mm` or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format) - `published_at_gt` (string) Retrieve stories published after the specified date (Formats: `yyyy-MM-dd HH:mm` or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format) - `published_at_lt` (string) Retrieve stories published before the specified date (Formats: `yyyy-MM-dd HH:mm` or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format) - `published_at_gte` (string) Retrieve stories published on or after the specified date (Formats: `yyyy-MM-dd HH:mm` or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format) - `published_at_lte` (string) Retrieve stories published on or before the specified date (Formats: `yyyy-MM-dd HH:mm` or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format) - `updated_at_gt` (string) Retrieve stories updated after the specified date (Formats: `yyyy-MM-dd HH:mm` or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format) - `updated_at_lt` (string) Retrieve stories updated before the specified date (Formats: `yyyy-MM-dd HH:mm` or [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format) - `excluding_fields` (string) Exclude specific fields of a content type by providing the field names as a comma-separated string. Example: `excluding_fields=body,meta_description` Note that excluding the `component` field from the response, the content of the story will be returned in the default language instead of a requested `language`. ## Response properties - `stories` An array of [story objects](/docs/api/content-delivery/v2/stories/the-story-object). - `rels` Array of resolved stories - `links` An array of resolved links - `rel_uuids` An array of all UUIDS of referenced stories (if the limit of resolvable relations is exceeded) - `link_uuids` An array of all UUIDS of linked stories (if the limit of resolvable links is exceeded) ## Examples - cURL ```shellscript curl "https://api.storyblok.com/v2/cdn/stories\ ?token=ask9soUkv02QqbZgmZdeDAtt\ &version=published\ &starts_with=articles" ``` - JS ```javascript // 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) } ``` - PHP ```php $client = new \Storyblok\Client('YOUR_STORYBLOK_SPACE_ACCESS_TOKEN'); $client->getStories([ "version" => "published", "starts_with" => "articles" ])->getBody(); ``` - Java ```java HttpResponse response = Unirest.get("https://api.storyblok.com/v2/cdn/stories?token=ask9soUkv02QqbZgmZdeDAtt&version=published&starts_with=articles") .asString(); ``` - C# ```csharp var client = new RestClient("https://api.storyblok.com/v2/cdn/stories?token=ask9soUkv02QqbZgmZdeDAtt&version=published&starts_with=articles"); var request = new RestRequest(Method.GET); IRestResponse response = client.Execute(request); ``` - Python ```python import requests url = "https://api.storyblok.com/v2/cdn/stories" querystring = {"token":"ask9soUkv02QqbZgmZdeDAtt","version":"published","starts_with":"articles"} payload = "" headers = {} response = requests.request("GET", url, data=payload, headers=headers, params=querystring) print(response.text) ``` - Ruby ```ruby require 'storyblok' client = Storyblok::Client.new(token: 'YOUR_TOKEN') client.stories({:params => { "version" => "published", "starts_with" => "articles" }}) ``` - Swift ```swift let storyblok = URLSession(storyblok: .cdn(accessToken: "ask9soUkv02QqbZgmZdeDAtt")) 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)) ``` - Kotlin ```kotlin val client = HttpClient { install(Storyblok(CDN)) { accessToken = "ask9soUkv02QqbZgmZdeDAtt" } } val response = client.get("stories") { url { parameters.append("version", "published") parameters.append("starts_with", "articles") } } println(response.body()) ``` Response ```json { "stories": [ { "name": "Mars Unveiled: Exploring the Mysteries and Marvels of the Red Frontier", "created_at": "2024-02-16T14:30:19.768Z", "published_at": "2024-03-13T17:20:40.220Z", "id": 445002665, "uuid": "a2c57c06-2c5c-4819-acb7-0d9c047d16e9", "content": { "_uid": "6bdf037c-f713-415c-a26a-8a9cfc926c85", "image": { "id": 14114865, "alt": "", "name": "", "focus": "", "title": "", "source": "", "filename": "https://a.storyblok.com/f/276232/3500x2000/cd4947ece2/mars.jpg", "copyright": "", "fieldtype": "asset", "meta_data": {}, "is_private": "", "is_external_url": false }, "author": "e7307a9e-a3c5-47ad-8f6c-a1a36fe528e2", "topics": ["space-exploration", "solar-system"], "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.", "headline": "Mars Unveiled: Exploring the Mysteries and Marvels of the Red Frontier", "component": "article", "scheduled": "2024-02-29 17:00", "categories": [ "45d968b6-5790-4fbb-aa41-5781b8edde51", "a6af7728-eadf-4428-8cf5-343304857374", "d8e48716-0ecf-4059-b568-343bf54e4128" ], "highlighted": false }, "slug": "mars-unveiled-exploring-mysteries-marvels-red-frontier", "full_slug": "articles/mars-unveiled-exploring-mysteries-marvels-red-frontier", "sort_by_date": null, "position": 0, "tag_list": [], "is_startpage": false, "parent_id": 444991588, "meta_data": null, "group_id": "2e0c427d-63ed-420e-830f-bf1889da0792", "first_published_at": "2024-02-16T14:30:11.990Z", "release_id": null, "lang": "default", "path": null, "alternates": [], "default_full_slug": null, "translated_slugs": null }, { "name": "Earth's Symphony: Navigating the Wonders and Challenges of Our Blue Oasis", "created_at": "2024-02-16T14:22:09.108Z", "published_at": "2024-03-13T17:20:40.506Z", "id": 444996765, "uuid": "660452d2-1a68-4493-b5b6-2f03b6fa722b", "content": { "_uid": "6bdf037c-f713-415c-a26a-8a9cfc926c85", "image": { "id": 14114772, "alt": "", "name": "", "focus": "", "title": "", "source": "", "filename": "https://a.storyblok.com/f/276232/2560x1946/ee938cf736/earth.jpg", "copyright": "", "fieldtype": "asset", "meta_data": {}, "is_private": "", "is_external_url": false }, "author": "51eed33d-855f-415c-ac0d-4404e03b89e1", "topics": ["solar-system"], "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.", "headline": "Earth's Symphony: Navigating the Wonders and Challenges of Our Blue Oasis", "component": "article", "scheduled": "2023-10-01 15:00", "categories": ["45d968b6-5790-4fbb-aa41-5781b8edde51", "d8e48716-0ecf-4059-b568-343bf54e4128"], "highlighted": false }, "slug": "earths-symphony-navigating-wonders-challenges-blue-oasis", "full_slug": "articles/earths-symphony-navigating-wonders-challenges-blue-oasis", "sort_by_date": null, "position": 0, "tag_list": [], "is_startpage": false, "parent_id": 444991588, "meta_data": null, "group_id": "8d99d18d-5c97-42cd-a646-51e0c553f26a", "first_published_at": "2024-02-16T14:30:11.990Z", "release_id": null, "lang": "default", "path": null, "alternates": [], "default_full_slug": null, "translated_slugs": null } ], "cv": 1710350440, "rels": [], "links": [] } ``` ## Pagination - [Previous: Retrieve a Single Story](/docs/api/content-delivery/v2/stories/retrieve-a-single-story) - [Next: The Story Object](/docs/api/content-delivery/v2/stories/the-story-object)