Evaluate query

Evaluate a CQL expression from your backend.

POST

https://api.croct.io/external/web/evaluate

Evaluates a CQL expression on behalf of a specific user and returns the result as a JSON value.

This is the server-side variant, intended for calls originating from your backend. It authenticates with an API key and applies rate limits tuned for backend traffic. For calls from a browser or device, use the client-side variant instead.

Example

Here is an example of how to evaluate an expression from a backend:

const response = await fetch('https://api.croct.io/external/web/evaluate', {  method: 'POST',  headers: {    'Content-Type': 'application/json',    'X-Api-Key': '<API KEY>',    'X-Client-Id': '<CLIENT ID>',    'X-Token': '<USER TOKEN>',    'X-Client-Ip': '192.0.2.10',    'X-Client-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',    'X-Client-Library': 'Custom Client v1.0.0',  },  body: JSON.stringify({    query: "user is returning",    context: {      timeZone: 'America/New_York',      page: {        url: 'https://example.com/pricing',        title: 'Pricing',        referrer: 'https://google.com',      },      campaign: {        name: 'summer-sale',        source: 'google',        medium: 'cpc',      },      attributes: {        plan: 'pro',      },    },  }),});
const result = await response.json();

Request headers

This endpoint accepts the following HTTP headers:

Content-Type string: Must be application/json.
X-Api-Key string: The API key to use for server-side requests.
Keep your API key safe
Never use your API key in client-side code, only in server-side environments.
X-Client-Id(optional) string: The ID of the client, in the form of a UUID.
This must be a persistent identifier that uniquely identifies the browser or device across sessions.
X-Token(optional) string: A base64-encoded JSON Web Token (JWT) that identifies the user.
Pass this header to use the identified user's context.
When the application enforces signed tokens, the JWT must be signed using an API key with the Issue user tokens permission, or the request fails with an authorization error.
Either X-Client-Id or X-Token must be present.
X-Client-Ip(optional) string: The IP address of the client.
Defaults to the IP of the incoming request. Passing a loopback address such as 127.0.0.1 also falls back to the request IP, which is useful for local development.
X-Client-Agent(optional) string: The user agent of the client.
Defaults to the User-Agent header of the incoming request.
X-Client-Library(optional) string: The SDK name and version, such as Croct SDK JS v0.20.0.
Used for usage statistics and feature switching to preserve backward compatibility across SDK versions.

Parameters

This endpoint accepts the following JSON body parameters:

query string

The CQL expression to evaluate.

Must be between 1 and 500 UTF-8 characters.

context(optional) object|null

Information about the user context, such as the time zone, page, and marketing campaign.

Used to provide additional signals to CQL expression evaluation.

timeZone(optional) string|null

The time zone of the user, represented by an IANA time zone ID, such as America/New_York.

Used in time-based CQL expressions.

page(optional) object|null

Information about the page the user is currently viewing.

url string: The URL of the page, such as https://www.example.com/products.
Required when page is provided.
title(optional) string|null: The title of the page, such as Products.
referrer(optional) string|null: The URL of the page that linked to the current page, such as https://www.google.com.

campaign(optional) object|null

Information about the marketing campaign that brought the user to the page.

These properties are compatible with the UTM parameters widely used in digital marketing for tracking and analytics.

name(optional) string|null: A unique identifier for the campaign. It is usually a short string, such as summer-sale or new-product-launch.
source(optional) string|null: The advertiser, site, or publication generating the traffic. For example, google, facebook, or newsletter.
medium(optional) string|null: The advertising or marketing channel used to reach the user. For example, email, video, or social.
content(optional) string|null: An identification of the specific ad or content the user interacted with. For example, main-banner or newsletter-cta.
term(optional) string|null: The keyword or term that triggered the ad. For example, running shoes or tennis racket.

attributes(optional) object|null

Custom key-value pairs available in CQL expressions through the context variable.

For example, suppose you pass the following attributes:

{"cities": ["New York", "San Francisco"]}

You can then reference them in queries like:

context's cities include location's cityName

The following restrictions apply:

Up to 30 entries and 5 levels deep
Keys can be either numbers or non-empty strings with a maximum length of 50 characters
Values can be null, numbers, booleans, strings (up to 50 characters), or nested maps
Nested maps follow the same constraints for keys and values

Response headers

X-Suspension-Reason(optional) string

The reason the API returned an empty response.

When the workspace has suspended services, the API returns 202 Accepted with an empty body and this header. Clients should treat this as a traffic control signal, not an error, and fall back to default behavior.

The possible values are:

Value	Description
tracking_and_personalization_suspended	The workspace has suspended services.

Response

The response body is the JSON-serializable result of the expression. The type depends entirely on the expression and can be a boolean, number, string, array, or object.

If the expression evaluates to a non-serializable type (such as a raw weekday, user, or session object), the request fails with an unserializable-result error instead.

Example response

The example query user is returning evaluates to a boolean:

true

An expression that selects an object returns the corresponding JSON object. For example, evaluating campaign returns:

{  "name": "summer-sale",  "source": "google",  "medium": "cpc",  "term": "pricing",  "content": "banner-a"}