New guide: AI is in production. Is your governance?

Announcing Visual Copilot - Figma to production in half the time

Builder.io
Builder.io
Contact sales

New guide: AI is in production. Is your governance?

Announcing Visual Copilot - Figma to production in half the time

Builder.io
Builder.io

Content API

With the Content API, you can make requests to retrieve data about any of your models within Builder. The Content API supports advanced query filtering with URL parameters to help you get exactly the data you need.

Use cases for querying data could include searches, populating content for a collection, or getting all links that meet certain criteria.

To access this data, write queries with dot notation and, optionally, MongoDB style operators.

For more details on querying, see the Querying Cheatsheet.

Note: Content published by Builder is immediately available to the Content API. If your application's visual interface does not reflect the changes you have made, check whether they have been published to the Content API.

Set up

To start using the Content API, make sure to import the Builder SDK into your project.

At the command line, use npm to install the Builder SDK:

npm install @builder.io/react

In your code, be sure to import the SDK:

import { builder } from "@builder.io/react";

Query requirements

To use the Builder Content API to retrieve data from your models, be sure to always provide the following request parameters in your queries:

  • Required: my-model-name (replace with your model's name)
  • Required: apiKey query param (replace with your Public API Key)

As an example, you'd replace my-model-name with the name of your model, such as page, and YOUR_API_KEY with your own Public API Key.

https://cdn.builder.io/api/v3/content/my-model-name?apiKey=YOUR_API_KEY

You can learn about the response structure using the Builder API Explorer.

No responses returned

If your API responses are coming back empty when querying, try the following:

  • Verify API Key format. You must apiKey, not apikey.
  • Ensure you've passed necessary targeting conditions. If your content has targeting conditions (like urlPath, device, or custom user attributes), you must pass the corresponding user attributes in your API request to receive a response.
  • Check your content's status. Verify that your content is published and currently active if it is scheduled.

Query performance

Not all query parameters perform equally. To get the best response times from the Content API, structure your queries to take advantage of Builder's database indexing.

Optimized targeting attributes

The two most performant targeting attributes are urlPath and locale. These fields are database-indexed, which means Builder can resolve matching content entries significantly faster when either or both are included in userAttributes.

import { builder } from "@builder.io/react";

const entry = await builder.get('my-model-name', {
  userAttributes: {
    urlPath: '/about',
    locale: 'en-US',
  },
})

Including urlPath or locale when possible or logically relevant greatly improves performance. The majority of Builder content is targeted against at least one of these two attributes, and this pattern is heavily optimized at the infrastructure level.

Tips for efficient querying

The following tips can be used to improve efficiency when using the Content API.

  • Always target by urlPath or locale when relevant. Queries that include these attributes consistently outperform queries that rely solely on other custom targeting attributes.
  • Avoid broad, untargeted queries at runtime. Using noTargeting: true or omitting userAttributes entirely fetches all entries without the benefit of indexing. Reserve these patterns for build-time use cases like static generation.
  • Use fields and omit to reduce payload size. Returning only the fields you need reduces both response time and bandwidth.
  • Use cachebust: true only at build time. Bypassing the cache produces the freshest data but significantly increases response times. Do not use it for runtime requests.
  • Lean on stale-while-revalidate caching. Builder serves content from the CDN edge cache while revalidating in the background. Keep staleCacheSeconds high for low-traffic content to maximize this benefit.

Solve common query issues

If your API responses are missing entries or returning fewer results than expected, the following patterns are common causes.

  • Draft entries do not have targeting. Draft entries in a model that have no targeting rules configured can interfere with query results. Review your model for unfinished draft entries and either configure targeting for them or remove them.
  • Your content is expired. A large volume of expired entries can affect query performance and skew results. Use excludeExpired: true to filter these out, or add startDate/endDate filters in your query param to scope results to an active date range.
  • Your cache is stale. If you've recently published changes that aren't appearing, the CDN cache may be serving an older version. Use cachebust: true to bypass the cache and confirm the latest data. Only use this for debugging or build-time use, not runtime requests.
  • Pagination is limiting the response. The default limit is 30 and the maximum per request is 100. If your model has more entries than that, use limit and offset together to paginate through all results.

Content API query params

This section covers the available Builder Content API query params.

apiKey

Use your API key when integrating with Builder.

import { builder } from "@builder.io/react";

builder.init(YOUR_API_KEY);

enrich

Set it to true include references and Symbols in the response, ensuring consistency between the Visual Editor and the live site.

For more information on enrich, read Fetching References and Symbols with enrich.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('model', {
  ...
  options: { enrich: true }
  ...
})

enrichOptions

When enriching data from the Content API, you may wish to exclude some fields or include only specific fields. When enrich is set to true, use the enrichOptions key to define precisely what information to receive.

enrichOptions accepts an object with two possible values:

  1. model: This key expects an object where each key is the name of a Model and each value is an object. Each object should include either the fields key, representing which fields to include, the omit key, representing which fields to exclude, or both keys.
  2. enrichLevel: This key accepts a value greater than 0 and determines the depth level for enriching. For example, an enrichLevel of 1 would return one additional nested model within the original response. The max level is 4.
import { builder } from "@builder.io/react";

const entry = await builder.get('post', {
  ...
  options: { 
    enrich: true,
    enrichOptions: {
      model: {
        author: {
          fields: "id,name,data",
          omit: "data.blocks",
        },
        category: {
          fields: "id,name",
        },
      },
      enrichLevel: 2,
    },
  },
  ...
})

The example above demonstrates a request to a post model with two nested models: author and category. For author, the name, id, and data values are included in the response, except the data.blocks value is exclude.

For the category model, only id and name are included in the response. Finally, with enrichLevel set to 2, two additional levels of depth will be included within the response, nested within the post model.

fetchTotalCount

Adding this key to your request returns a totalCount key with the total number of results for the model. This number can be used for pagination or other use-cases where the total number of results is useful to know.

import { builder } from "@builder.io/react";

const entry = await builder.get('post', {
  fetchTotalCount: true,
  ...
})

query

MongoDB style query of your data.

import { builder } from '@builder.io/react'

// replace model with your model name
const entry = await builder.get('my-model-name', {
  query: {
    id: 'abc123',
    data: {
      myCustomField: 'someValue',
      someNumber: { $ne: 2 }
    }
  }
}

// to get all entries from a page model that are using a specific symbol
// where SYMBOL_ID is your Symbol's ID
const entry = await builder.get('page', {
  query: {
    'meta.symbolsUsed.SYMBOL_ID': true
  }
});

userAttributes

Use it to specify targeting attributes, such as urlPath, device, and any of the defined custom targeting, to fetch the most relevant entry when the model contains multiple entries.

By default, the response is limited to one entry. Without targeting attributes, it will only include the topmost entry.

If you pass in a date value to the date param, you can override Builder's default behavior, which uses the server's current time.

For more details on user attributes, read targeting content. For important information regarding targeting and scheduling and the Content API, see Scheduling behavior later in this document.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  userAttributes: {
    urlPath: '/about',
    device: 'desktop',
    userLoggedIn: true,
    // optional date param for scheduling
    date: "12-01-2025"
  },
})

fields

Only include the specified fields from the response.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  fields: 'id,name,data.customField'
})

omit

Exclude only specific fields from the response and return everything else.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  omit: 'data,bigField,data.blocks'
})

noTargeting

Builder applies targeting and personalization rules based on attributes like urlPath, device, and custom targeting attributes. To retrieve all the content entries regardless of targeting rules, set noTargeting to true in the options parameter.

For important information regarding targeting and scheduling and the Content API, see Scheduling behavior later in this document.

import { builder } from "@builder.io/react";

// replace model with your model name
const allEntries = await builder.getAll('my-model-name', {
    options: { noTargeting: true }
})

limit

Maximum number of results to return. The default is 30 and the maximum is 100.

import { builder } from "@builder.io/react";

// replace model with your model name
const allEntries = await builder.getAll('my-model-name', {
    limit: 10,
    // This will retrieve all content entries
    options: { noTargeting: true }
  })

By default, Builder applies targeting rules based on attributes like urlPath, device, and custom targeting attributes. To retrieve all content entries, call builder.getAll() and set noTargeting to true in the options parameter.

offset

Use to specify an offset for pagination of results. The default is 0. 

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  offset: 10
})

To fetch all content beyond the limit of 100, use limit and offset together by paginating results and making multiple API calls as follows:

const limit = 100;
let offset = 0;
const pages = await getResults({limit, offset});
while(pages.length === (limit + offset)) {
  offset += pages.length;
  pages.push( ... (await getResults({ limit, offset})));
}
return pages;

For more detail, see this forum post and this forum post.

includeRefs

Include content of references in response.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  includeRefs: true
})

cacheSeconds

Seconds to cache content. This sets the maximum age of the cache-control header response . Set value higher for better performance, and lower for content that changes frequently.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  cacheSeconds: 10
})

staleCacheSeconds

Builder uses stale-while-revalidate caching at the CDN level, serving content from the edge cache while updates occur in the background for optimal performance.

The more frequently content is requested, the fresher it becomes. By default, Builder holds content in the stale cache for up to one day, but you can adjust this to a shorter duration if needed.

The minimum value for staleCacheSeconds is 1 hour, or 3600 seconds.

We recommend keeping this duration high unless you have low-traffic content that must update rapidly.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  staleCacheSeconds: 86400
})

sort

Use the property to order results by setting the value to 1 for ascending and -1 for descending.

The key specifies the field to sort on. For example, sorting by createdDate with a value of 1 results in ascending order.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  sort: {
    createdDate: 1
  }
})

excludeExpired

Exclude content entries that have passed their scheduled end date from the response. Use this when querying without targeting attributes to ensure expired entries are not returned.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  excludeExpired: true
})

excludeScheduled

Exclude content entries whose scheduled start date has not yet been reached. Use this to ensure only currently active entries are returned when querying without targeting attributes.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  excludeScheduled: true
})

includeUnpublished

Include content entries in a response that are still in draft mode and unarchived.

Important: You can restrict this option with a Space setting. See Restrict public API access below for details.

For important information regarding targeting and scheduling and the Content API, see Scheduling Behavior later in this document.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  includeUnpublished: true
})

published.$ne

Use published.$ne as a query filter to exclude entries based on their publish state. This uses the MongoDB-style "not equal", $ne, operator against the published field, which has three possible values: 'published', 'draft', and 'archived'.

The most common use is published.$ne=archived, which returns both published and draft entries while excluding archived ones.

import { builder } from "@builder.io/react";

// replace model with your model name
const entries = await builder.getAll('my-model-name', {
  options: { noTargeting: true },
  includeUnpublished: true,
  query: {
    published: { $ne: 'archived' }
  }
})

Because published.$ne can expose draft content, it is subject to the same access restriction as includeUnpublished. If your space has Restrict Public API Key from Querying Unpublished Content enabled, this filter is blocked for the public API key and requires a Private API Key. See Restrict public API access to unpublished content for details.

Restrict public API access to unpublished content

By default, the Public API Key can query draft and archived content using includeUnpublished: true or published.$ne filters. If you want to prevent public access to unpublished content, you can enable the Restrict Public API Key from Querying Unpublished Content setting.

When enabled:

  • The public API key cannot use includeUnpublished: true or published.$ne filters.
  • Only a Private API Key can query draft or archived content.

This setting is useful for preventing accidental exposure of draft or unfinished content in production environments.

To enable this setting, go to Settings → Advanced Settings → Advanced in your Space Settings.

noTraverse

Though the default is true, you can pass false to include Symbol JSON in the response. This is helpful if you want to render your page all at once such as in server-side rendering.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  noTraverse: false
})

cachebust

Set this to true to ensure you get the most up-to-date data. This may be particularly relevant for frequently changing content or situations where updated information is preferred.

This will bypass the default cache settings. Note that as a result response times will be significantly slower when using this option.

import { builder } from "@builder.io/react";

// replace model with your model name
const entry = await builder.get('my-model-name', {
  cachebust: true
})

Only set cachebust to true in the SDKs or APIs for build-time requests, such as when statically generating Pages, as response times will be slow when bypassing all caching. We do not recommend it for runtime requests — such as when serving Pages.

If intentionally choosing to bypass Builder's cache, it is highly recommended to provide your own cache layer to reduce the impact of potential service disruptions.

Fetch modifications

Request functionality can be modified in the following ways.

fetch

Use the fetch option to override the default behavior of the global fetch() function used in the API.

This is helpful for:

  • Adding specific headers or handling authentication
  • Using libraries like Axios
  • Defining custom HTTP request logic, such as integrating custom agents

The fetch property expects a function with the same parameters as the global fetch() function. It takes url.href as the first parameter and optionally a configuration object as the second.

For more information, see fetch() parameters.

The fetch option does not apply to Gen 1 frameworks.

fetchOptions

Specifies additional RequestInit options to configure the overridden fetch request, including:

  • headers for custom request headers
  • credentials to control authentication
  • keepalive for background requests and sending analytics
  • method to define the HTTP method

Keep in mind that fetchOptions can be used regardless of whether or not fetch was modified, and is usable in both Gen 1 and Gen 2 SDKs.

import { builder } from "@builder.io/react";

const MyFetchOptions: RequestInit = {
  method: "GET",
  cache: "no-cache", 
  keepalive: true // Ensures the connection remains open for reuse
}

// replace model with your model name
const entry = await builder.get('my-model-name', {
  fetchOptions: MyFetchOptions
})

Content API v3 is currently the default. Learn more in Content API Versions.

Scheduling behavior

Builder content scheduling using startDate and endDate is only checked if all of the following conditions are met:

  • userAttributes are included in the request
  • noTargeting is not passed or is set to false

If these conditions are met, then Builder includes a content entry if the current time falls between the entry's startDate and endDate.

By default, Builder uses the server's current time. You can override this by passing a date value in userAttributes.date.

Scheduling and references

If a reference's schedule is invalid, it is skipped and not included in the response.

If you're debugging missing content in API responses, make sure userAttributes are included and that you are not disabling targeting or scheduling unintentionally.

To experiment with the Content API, you can use the Builder API Explorer, which offers a way for you to compose queries in your own Builder Space. This way, you can confirm that your queries are correct before editing your code base.

Text that reads, "Try the API Explorer". Under the text is a curved arrow pointing to a tile to the right

Builder API Explorer

Was this article helpful?

Product

Visual CMS

Theme Studio for Shopify

Sign up

Login

Featured Integrations

React

Angular

Next.js

Gatsby

Resources

User Guides

Developer Docs

Forum

Blog

Github

Get In Touch

Chat With Us

Twitter

Linkedin

Careers

© 2020 Builder.io, Inc.

Security

Privacy Policy

Terms of Service

Get the latest from Builder

By submitting, you agree to our Privacy Policy.

Platform

  • Fusion

  • Publish

  • Product Updates

Use Cases

Developer Resources

Frameworks

  • Design to Code

    >

  • CMS

    >

  • Page Builder

    >

Workflows

Resources

Popular Guides

  • Figma to Code Guide

  • Headless CMS Guide

  • Headless Commerce Guide

  • Composable DXP Guide

Company

Security

Privacy Policy

SaaS Terms

Trust Center

Cookie Preferences