Retrieve Multiple Stories

The content version to retrieve: draft or published. Default is published. Retrieving draft requires a preview access token.

Cached version Unix timestamp. Learn more in the Caching concept.

Filter by the story’s full_slug to return items starting with the given value.

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 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.

The number of items per page in a paginated response.

Page number in a paginated response.

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/*.

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*.

Retrieve stories published after the specified date. Supports ISO 8601.

Retrieve stories published on or after the specified date. Supports ISO 8601.

Retrieve stories published before the specified date. Supports ISO 8601.

Retrieve stories published on or before the specified date. Supports ISO 8601.

Retrieve stories first published after the specified date. Supports ISO 8601.

Retrieve stories first published at or after the specified date. Supports ISO 8601.

Retrieve stories first published before the specified date Supports ISO 8601.

Retrieve stories first published at or before the specified date. Supports ISO 8601.

Retrieve stories updated after the specified date. Supports ISO 8601.

Retrieve stories updated at or after the specified date. Supports ISO 8601.

Retrieve stories updated before the specified date. Supports ISO 8601.

Retrieve stories updated at or before the specified date. Supports ISO 8601.

Retrieve stories in a particular workflow stage by providing a comma-separated list of workflow stage IDs. For example, in_workflow_stages=325604,325605.

Retrieve stories of a specific content type block. For example, content_type=page.

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.

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.

Exclude specific stories by IDs in a comma-separated string. For example, excluding_ids=335015953,335015954.

Retrieve specific stories by UUIDs in a comma-separated string. For example, by_uuids=a78b2116-c26d-4d23-9cbe-fec477847b0e,9683820e-fc17-429e-ba23-eb41f26c0776.

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.

Retrieve items by id. Supports a comma-separated 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.

Filter by stories defined as root for the folder.

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 up to two levels of links.

To resolve the links inside related stories, set resolve_links_in_relations=1. This parameter requires both resolve_relations and resolve_links.

The links property of the response includes both the story’s own links and the ones returned from the related stories.

Links in resolve_level=2 relations remain unresolved.

When exceeding the limit, the response includes link_uuids instead of links.

Access a story version in a specific release by providing the release ID.

Define a custom fallback language to handle untranslated fields. Supports languages defined in Settings → Internationalization. Provide language code with underscores. For example, es_co instead of es-co.

Retrieve translated story version. Supports languages defined in Settings → Internationalization.

Learn more in Filter Queries.

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.

When a request has both excluding_fields and including_fields, the API ignores excluding_fields.

To return only specific fields of a content type, provide the field names as a comma-separated string. For example, including_fields=title,image.

The response always returns _uid, component, and _editable, as well as translated versions of a listed field.

Takes precedence over excluding_fields.

Exclude top-level story response fields with a comma-separated list. For example, excluding_story_fields=alternates,translated_slugs.

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.

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.

When set, returns only experiment variant stories.

A preview or public access token configured in a space.