HomeGuidesAPI ReferenceGraphQL
Submit Documentation FeedbackJoin Developer CommunityOptimizely GitHubOptimizely NuGetLog In

Core Concepts

Getting Started with GraphQL

What is GraphQL?

GraphQL is a query language for data that is available via API. It allows the developer to ask for exactly the data wanted, in the shape wanted.

Relative to a REST API, GraphQL has the following benefits:

  • Ability to ask for the fields needed, rather than provide all the fields
  • Well-supported, good client libraries
  • Allows for joins between data dimensions in a real-time request

For more information, visit https://graphql.org/.

GraphQL and REST APIs with ODP

Bulk events

For events across many customers use the Optimizely Data Platform (ODP) Exports API.
Example: Export all send events for a particular campaign.

Bulk Dimensions

For bulk dimensions (either all values or values filtered in a particular way) you can use either GraphQL or the ODP Exports API. We recommend using the ODP Exports API anytime you expect more than 1,000 entities in your result. The maximum page size in GraphQL is 1,000 and cursors can be used to retrieve multiple pages; however, the latency cost of paginating through will eventually exceed the latency overhead of the ODP Exports API, making Exports the more performant option.

Example: Export all customers with their consent status. Use the Exports API.

Example: Export all customers with have opted-out in the last hour. Use GraphQL.

Point data that crosses dimensions

For data about a single thing (like a set of events or a customer), but which requires joining across dimensions (such as adding product details), use the GraphQL endpoint. This endpoint allows for joins on a single point in real time across dimensions.

Example: Retrieve details about a purchase, and add in product details like the name and image URL.

Single-purpose point data

For data limited to a single point on a single dimension, either approach is available and it's a matter of preference. However, for performance reasons, ODP recommends GraphQL.

Example: Retrieve consent or reachability details for an identifier.

GraphQL terminology

Throughout the documentation you will come across with following terminologies.


The schema defines ODP GraphQL type system. It describes the complete set of possible data (objects, fields, relationships) that a client can access. For more information, see "Discovering the GraphQL API."


A field is a unit of data you can retrieve from an object. It is explained in GraphQL docs as "GraphQL query language is basically about selecting fields on objects."


An argument is a set of key-value pairs attached to a specific field. It can be either required or optional depending on the implementation.


Connections allow you to query related objects as part of the same call. With connections, you can use a single GraphQL call where you would have to use multiple calls to a REST API. For example, Point data that crosses dimensions


Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every edges field has a node field and a cursor field. Cursors are used for pagination.


Node represents object. You can look up a node directly, or you can access related nodes via a connection. If you specify a node that does not return a scalar, you must include subfields until all fields return scalars.

Discovering the GraphQL API

GraphQL is introspective which means you can query a GraphQL schema for details about itself.

Using GraphQL Explorer

Explore the schema and test queries using our GraphiQL UI.

For most dimensions, filtering is only available by the primary key(s). For special dimensions, like events and customers, additional filter options are available to specify the data returned. Explore the schema by clicking "Query" in the Documentation Explorer, or searching for a specific field.

All dimensions available in the account can be queried. Custom dimensions vary by account, but standard dimensions include:

  • events
  • customer
  • order
  • product
  • list
  • list_member
  • customer_observation
  • customer_insight
  • product_observation
  • product_insight
  • compliance

View custom dimensions on the account's Objects & Fields page.

Using GraphQL API

  • Query __schema to list all types defined in the schema and get details about each:
query {
  __schema {
    types {
      fields {
  • Query __type to get details about any type:
query {
  __type(name: "Customer") {
    fields {

Did this page help you?