Evaluate query

Evaluates a CQL expression against the current user context and returns the result as a JSON value.

This is the client-side variant, intended for calls originating from a browser or device. It authenticates with the public application ID, enforces CORS checks against the application's trusted origins, and applies rate limits tuned for browser traffic. For calls from your backend, use the server-side variant instead.

Example

Here is an example of how to evaluate an expression:

const response = await fetch('https://api.croct.io/client/web/evaluate', {  method: 'POST',  headers: {    'Content-Type': 'application/json',    'X-App-Id': '<APP ID>',    '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-App-Id

string

The public application ID to use for client-side requests.

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.

Either X-Client-Id or X-Token must be present.

X-Token(optional)

string

A base64-encoded JSON Web Token (JWT) that identifies the user.

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

Origin(optional)

string

The origin of the request.

Must match one of the application's trusted origins. Browsers set this header automatically.

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"}