Filter Queries with Field-level Translation

It is possible to use filter queries with stories translated using Storyblok’s field-level translation. The field key must be extended with __i18n__ and a language code configured in the space settings. The following syntax applies:

stories/?filter_query[field__i18n__language_code][operation]=value

The following criteria must be fulfilled to successfully use filter queries with translated stories:

• The space must be configured to publish languages independently.
• The space must be configured to have use_filter_query_in_translated_stories enabled.
• The request must contain the language parameter specifying the target language.
• The request must contain version=published.

Note

For spaces created before February 6th, 2024, please contact Storyblok’s support team to enable the internal use_filter_query_in_translated_stories option. For spaces created after February 6th, 2024, this option is enabled by default.

Examples Use Cases

• filter_query[description__i18n__de][like]=Deutsches*

  Returns all stories whose description starts with the word “Deutsches” and are published in German, represented by the language code de.

• filter_query[headline__i18n__es_co][like]=Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul

  Returns all stories with this exact headline that are published in Spanish (Colombia), represented by the language code es-co.

Caution

Please note that the language code needs to be formatted with an underscore in the filter_query (es_co), even if it is defined with a hyphen in the space settings (es-co).

Example Request and Response

cURL

curl "https://api.storyblok.com/v2/cdn/stories\
?filter_query%5Bdescription__i18n__de%5D%5Blike%5D=Deutsches*\
&language=de\
&version=published\
&token=ask9soUkv02QqbZgmZdeDAtt"

JS

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

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

try {
  const response = await storyblok.get('cdn/stories', {
    "filter_query[description__i18n__de][like]": "Deutsches*",
    "language": "de",
    "version": "published"
  })
  console.log({ response })
} catch (error) {
  console.log(error)
}

PHP

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

$client->getStories([
  "filter_query[description__i18n__de][like]" => "Deutsches*",
  "language" => "de",
  "version" => "published"
])->getBody();

Java

HttpResponse<String> response = Unirest.get("https://api.storyblok.com/v2/cdn/stories?filter_query%5Bdescription__i18n__de%5D%5Blike%5D=Deutsches*&language=de&version=published&token=ask9soUkv02QqbZgmZdeDAtt")
  .asString();

C#

var client = new RestClient("https://api.storyblok.com/v2/cdn/stories?filter_query%5Bdescription__i18n__de%5D%5Blike%5D=Deutsches*&language=de&version=published&token=ask9soUkv02QqbZgmZdeDAtt");
var request = new RestRequest(Method.GET);

IRestResponse response = client.Execute(request);

Python

import requests

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

querystring = {"filter_query[description__i18n__de][like]":"Deutsches*","language":"de","version":"published","token":"ask9soUkv02QqbZgmZdeDAtt"}

payload = ""
headers = {}

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

print(response.text)

Ruby

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

client.stories({:params => {
  "filter_query[description__i18n__de][like]" => "Deutsches*",
  "language" => "de",
  "version" => "published"
}})

Swift

// .package(url: "https://github.com/storyblok/storyblok-swift.git", from: "1.1.0")
// Requires a `Block` content model — see https://www.storyblok.com/docs/quickstarts/apple-platforms/content-modeling
let client = StoryblokClient(
    library: Block.self,
    accessToken: "ask9soUkv02QqbZgmZdeDAtt",
    version: .published,
    region: .eu,
    language: "de"
)

let stories: Page<Story<Block>>? = try await client
    .stories { @Sendable (query: inout StoriesQuery<Block>) in
        query.parameter("filter_query[description__i18n__de][like]", "Deutsches*")
    }
    .last()
    .values
    .first { @Sendable _ in true }

print(stories!)

Kotlin

// implementation("com.storyblok:content-api-client:0.7.1")
val client = StoryblokClient(
    accessToken = "ask9soUkv02QqbZgmZdeDAtt",
    version = Published,
    language = "de",
)

val stories = client
    .stories {
        parameter("filter_query[description__i18n__de][like]", "Deutsches*")
    }
    .flow
    .asItemSnapshotListFlow()
    .first()

println(stories)

Response

{
  "stories": [
    {
      "name": "Spaceship",
      "created_at": "2018-12-10T17:51:25.161Z",
      "published_at": "2026-10-08T14:09:59.811Z",
      "updated_at": "2026-10-23T07:57:15.794Z",
      "id": 461935,
      "uuid": "14d950c6-0a8f-4088-98e3-73efced9ff6d",
      "content": {
        "_uid": "00b45e23-5dc5-4398-9b34-e87ae4ed42e6",
        "link": {
          "id": "273bba42-834b-4a87-b190-eafe3eabb4d4",
          "url": "",
          "linktype": "story",
          "fieldtype": "multilink",
          "cached_url": "/de/home",
          "prep": true
        },
        "name": "Raumschiff",
        "image": "//a.storyblok.com/f/44203/6016x4016/995fde1190/spaceship.jpg",
        "price": "1700000007",
        "featured": true,
        "component": "product",
        "description": "Deutsches Lorem ipsum dolor sit amet, consectetur adipiscing elit. In erat mauris, faucibus quis pharetra sit amet."
      },
      "slug": "spaceship",
      "full_slug": "de/products/spaceship",
      "sort_by_date": null,
      "position": -30,
      "tag_list": [],
      "is_startpage": false,
      "parent_id": 461931,
      "meta_data": null,
      "group_id": "99285e65-5610-4ff1-a0c7-a037f9b84e5d",
      "first_published_at": "2026-10-08T14:09:59.811Z",
      "release_id": null,
      "lang": "de",
      "path": null,
      "alternates": [],
      "default_full_slug": null,
      "translated_slugs": null
    }
  ],
  "cv": 1792742236,
  "rels": [],
  "links": []
}