Convert API (2.0.0)

Download OpenAPI specification:Download

Move your app forward with the Convert API. The Convert API allows you to manage your Convert Experiences projects using code. The REST API is an interface for managing and extending functionality of Convert. For example, instead of creating and maintaining projects using the Convert Experiences web dashboard you can create an experiment programmatically. Additionally, if you prefer to run custom analysis on experiment results you can leverage the API to pull data from Convert Experiences into your own workflow. If you do not have a Convert account already, sign up for a free developer account at https://www.convert.com/api/.

Convert API V1 is still available and documentation can be found here but using it is highly discouraged as it will be phased out in the future

API KEY Authentication

Convert API supports two methods of API key authentication:

  1. Request Signing (HMAC)

When using request signing, Convert API uses the Hash-based message authorization code (HMAC). Instead of having passwords that need to be sent over, we actually use Signing Method for API request validation. When you send HTTP requests to Convert, you sign the requests so that Convert can identify who sent them. So every request should contain Signature, calculated with the help of a Secret Key, Request URL, Request payload, Request Expiration time.

Three headers have to be sent with each request in order for the request to be authenticated correctly by Convert API:

  • Convert-Application-ID: This is the ID you get from your account corresponding to the application created inside Convert App.
  • Expires: This is a UNIX timestamp after which the request signing expires. The closer in future the timestamp is, the sooner the request signature would be invalidated and the more secure would be
  • Authorization: The value of this one is as follows: Convert-HMAC-SHA256 Signature=[generated_hash]; The [generated_hash] is a request signature calculated applying sha256 hashing algorithm on ApplicationID, ExpiresTimestamp, RequestURL, RequestBody.

What could go wrong with request signing authorization? APP ID and APP Secret are right, but it is still UNAUTHORIZED!

  • Check your system time - the time of the system where signature is generated
  • Check the request duration between client and API and provide larger expiration time if it takes longer so that signature does not expire before reaching validation on Convert's servers
  • Make sure that stringified payload and Sign String are correct and do not contain additional spaces. For Javascript just use JSON.stringify(request) for request payload. For php use additional flags for json_encode: json_encode($request, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)).
  • Make sure you are using HMAC SHA256 to calculate the signature and provide this method (Convert-HMAC-SHA256) in the Authorization header value
  • Make sure that nothing changes the payload after signature generation but before sending it

Example of the request signing signature generation in Javascript:

var SignString  = ApplicationID + "\n" + ExpiresTimestamp + "\n"  + RequestURL + "\n" + RequestBody;
var hash = CryptoJS.HmacSHA256(SignString, ApplicationSecretKey);
var hashInHex = CryptoJS.enc.Hex.stringify(hash);
var Authorization = "Convert-HMAC-SHA256 Signature=" + hashInHex;

For the above example, the Authorization header would be "Authorization: Convert-HMAC-SHA256 Signature=${Authorization}"

  1. Secret Key

A simpler authentication method using a shared secret key. This method requires only a single header:

  • Authorization: Include the key ID and key secret as a Bearer token in the format: Bearer KEY_ID:KEY_SECRET

The secret key method is easier to implement while still providing strong security. However, request signing provides additional security through request expiration and payload validation.

Cookie Authentication

In order to use the Convert app, user has two options to authenticate requests:

  • Provide authorization token with each request works best for backend systems
  • Authenticate once using username/password/IDP provider and than send session token together with each request These endpoints will handle second case.

IMPORTANT: currently this is available only for Convert.com's own clients, all other third party clients need to authenticate using API KEY Authentication

Authenticate user session (Cookie Based)

Initiates or continues a cookie-based authentication flow. Starts with username/password. If successful and MFA is not required, returns user data and sets a session cookie. If MFA is required, or a new password needs to be set, the response will indicate the next step and provide a sessionToken. This is primarily for UI interaction, LLMs should typically use API Key Authentication.

Request Body schema: application/json

Contains the necessary credentials or tokens for a user to authenticate their session, typically including username and password or MFA codes for cookie-based authentication.

username
string
requestType
required
string
object (PasswordAuthData)

Base data included in cookie-based authentication steps.

Responses

Request samples

Content type
application/json
Example
{
  • "username": "string",
  • "requestType": "initiatePasswordAuth",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "auth-code": "NEW_PASSWORD_REQUIRED",
  • "message": "string",
  • "data": {
    }
}

Request password reset

Sends an email with a password reset link to the user associated with the provided email address, if an account exists. This is part of the cookie-based authentication flow.

Request Body schema: application/json

Contains the username (typically email) of the user who has forgotten their password and is requesting a reset link for cookie-based authentication.

username
string

The username or email address associated with the account for which password reset is requested.

Responses

Request samples

Content type
application/json
{
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Confirm new password after reset request

Completes the password reset process. The user provides the new password and the confirmation code received via email. This is part of the cookie-based authentication flow.

Request Body schema: application/json

Includes the new password, confirmation of the new password, and the reset code received by the user to finalize the password reset process for cookie-based authentication.

authSub
string

(Deprecated or Internal) An internal user identifier, typically part of the password reset link sent via email. The token or code is usually the primary field.

code
required
string

The password reset confirmation code received by the user via email. This code verifies the reset request.

newPassword
required
string

The new password chosen by the user. Must meet system complexity requirements. Maximum length is 99 characters.

confirmNewPassword
required
string

Confirmation of the new password. Must exactly match the newPassword field. Maximum length is 99 characters.

token
string

(Deprecated or Alternative) A password reset token, possibly sent as part of the reset link. The code field is often the primary verification.

Responses

Request samples

Content type
application/json
{
  • "authSub": "string",
  • "code": "string",
  • "newPassword": "string",
  • "confirmNewPassword": "string",
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "auth-code": "NEW_PASSWORD_REQUIRED",
  • "message": "string",
  • "data": {
    }
}

Log out user session

Invalidates the current authenticated user session (cookie-based). Can also be used to log out other or all sessions for the user.

Request Body schema: application/json

Specifies which user sessions to invalidate (e.g., current, other, or all sessions for the authenticated user) for cookie-based authentication.

requestType
string
Enum: "currentSession" "otherSessions" "allSessions"

Responses

Request samples

Content type
application/json
{
  • "requestType": "currentSession"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Check authentication status

Verifies if the current cookie-based session is still valid and authenticated.

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Optional Fields

Each response returned by API endpoints can have fields that are not returned by default, for improved performance, in many use cases where those fields would not be needed.

Important: Object returned as a response of a created/update operation would include also the optional fields of that object.

Those requests which can return optional fields specify the list of possible values for those fields names in an include parameter, described either as part of the URL, either as part of the request body.

Format

The include parameter must be an array when present. In URL parameters, use the following format:

include[]=field1&include[]=field2

Valid Examples

  • Including stats and variations in an experience response:
    include[]=stats&include[]=variations
    
  • Including rules and stats in an audience response:
    include[]=rules&include[]=stats.experiences_usage
    

Error Cases

  • Invalid format (string instead of array):
    include=stats  # ❌ Wrong
    include[]=stats  # ✅ Correct
    
    Response:
    {
      "code": 422,
      "message": [
          "The 'include' parameter must be a array."
      ],
      "parameters": [
          "include"
      ]
    }
    

Fields mentioned in the include parameter can belong to Expandable Fields in which case that respective field would be expanded by default. Example: include[]=variations.changes for a getExperience operation, variations.changes is an expandable field of that response, which would then be expanded by default.

Expandable Fields

Each response returned by API endpoints can have fields that reference other objects, which are not returned in full by default. For example, the getExperience operation returns and Experience object which contains a project field. By default, this is a string and represents the ID of the referenced project object.

In some use cases, more data related to the respective object might be needed. The Convert API offers the ability to expand certain fields into a more detailed object identified by the ID that would be sent by default.

The expanded object is the same object that the get[Object] operation would return, not having though any of the Optional fields

Format

The expand parameter must be an array when present. In URL parameters, use the following format:

expand[]=field1&expand[]=field2

Valid Examples

  • Expanding project and audiences in an experience response:
    expand[]=project&expand[]=audiences
    
  • Expanding goals and variations in an experience response:
    expand[]=goals&expand[]=variations
    

Error Cases

  • Invalid format (string instead of array):
    expand=project  # ❌ Wrong
    expand[]=project  # ✅ Correct
    
    Response:
    {
      "code": 422,
      "message": [
          "The 'expand' parameter must be a array."
      ],
      "parameters": [
          "expand"
      ]
    }
    

User

Authenticated user related endpoints

List available user access roles

Retrieves a list of all predefined access roles within the Convert system (e.g., Owner, Admin, Editor, Reviewer, Browse). Each role defines a set of permissions that dictate what actions a user can perform on accounts and projects. This is useful for understanding permission levels when managing collaborators.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get current authenticated user's details

Retrieves the profile data, preferences, and settings for the currently authenticated user (via cookie). This includes information like email, name, and UI preferences. Note: This endpoint is for cookie-based authentication. For API key authentication, user context is tied to the key itself.

Responses

Response samples

Content type
application/json
{
  • "profileData": {
    },
  • "preferences": {
    },
  • "isSudo": true,
  • "mfa_backup_codes": [ ]
}

Update current user's profile

Allows the authenticated user (via cookie) to update their profile information, such as name, email, or password. Also used to manage Multi-Factor Authentication (MFA) settings. User preferences (like UI display settings) are managed via a separate endpoint.

Request Body schema: application/json

Contains user profile fields to be updated for cookie-based authenticated users, such as first name, last name, email, current password (for verification), new password, or MFA settings.

firstName
string <= 200 characters

The user's new first name.

lastName
string <= 200 characters

The user's new last name.

currentPassword
string <= 25 characters

The user's current password. Required if changing email or password.

newPassword
string <= 25 characters

The new password chosen by the user. Required if changing password. Max 25 chars.

confirmPassword
string <= 25 characters

Confirmation of the new password. Must match newPassword. Required if changing password. Max 25 chars.

email
string <email> <= 100 characters

The user's new email address. Requires currentPassword for verification.

any

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "currentPassword": "string",
  • "newPassword": "string",
  • "confirmPassword": "string",
  • "email": "user@example.com",
  • "mfa": {
    }
}

Response samples

Content type
application/json
{
  • "profileData": {
    },
  • "preferences": {
    },
  • "isSudo": true,
  • "mfa_backup_codes": [ ]
}

Confirm user email address change

Finalizes an email address change request by submitting the confirmation code sent to the new email address. Used in cookie-based authentication flows.

Request Body schema: application/json

Contains the confirmation code sent to the user's new email address to verify and complete an email change request for cookie-based authenticated users.

code
required
string

The unique verification code sent to the user's new email address. Submitting this code confirms the email change.

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "profileData": {
    },
  • "preferences": {
    },
  • "isSudo": true,
  • "mfa_backup_codes": [ ]
}

Update user's UI preferences

Allows the authenticated user (via cookie) to update their preferences for the Convert application UI, such as default column visibility in tables or editor settings. These settings do not affect experiment behavior.

Request Body schema: application/json

A JSON object specifying the user's UI preferences to be updated for cookie-based authenticated users, such as editor settings or default display options for lists. These do not affect experiment execution.

object
object
object or null
notificationsSeen
Array of strings
Items Value: "TODO-define-it"
object
mfaEnabled
boolean

True if Multi-Factor Authentication (MFA) is currently enabled for this user's account.

Responses

Request samples

Content type
application/json
{
  • "editorSettings": {
    },
  • "displaySettings": {
    },
  • "uiSettings": {
    },
  • "notificationsSeen": [
    ],
  • "generalSettings": {
    },
  • "mfaEnabled": true
}

Response samples

Content type
application/json
{
  • "profileData": {
    },
  • "preferences": {
    },
  • "isSudo": true,
  • "mfa_backup_codes": [ ]
}

Generate MFA secret for authenticator app

Generates a new Multi-Factor Authentication (MFA) secret for the authenticated user (cookie-based). This secret is used to set up an authenticator app (like Google Authenticator) for generating time-based one-time passwords (TOTPs).

Responses

Response samples

Content type
application/json
{
  • "mfa_secret": "string"
}

Accept and create a demo project for the user

Allows a user to accept the creation of a pre-configured demo project in their account. This is typically used for onboarding or trial experiences to showcase Convert's features.

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Accounts

Account is the entity that contains all data. An account is owned by an user and in which more other users can have different permissions, account wide or at project level

List accounts accessible to the user

Retrieves a list of all accounts the authenticated user has access to. If using API key authentication, this typically returns the single account associated with the API key. If using cookie-based authentication, it may return multiple accounts if the user is a collaborator on several. An account is the top-level container for projects, billing, and user management.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List available billing plans

Retrieves a list of all active billing plans that an account can subscribe to. Each plan defines usage limits (e.g., tested visitors, number of projects) and available features.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get live tracking events for an account

Retrieves the last 100 tracking events (e.g., experiment views, goal conversions) across all projects within the specified account. Useful for real-time monitoring of activity. Supports filtering by event types and specific projects. As per the Knowledge Base, "Live Logs in Convert track how end users are interacting with web pages and experiments...at a project and experiment level in real time."

path Parameters
account_id
required
integer

ID of the account to be retrieved

Request Body schema: application/json

Optional filters for retrieving live tracking events for an entire account. You can specify particular project IDs or event types (e.g., 'view_experience', 'conversion') to narrow down the results. Useful for a real-time overview of all activities.

event_types
Array of strings or null (LiveDataEventTypes)
Enum: "view_experience" "conversion" "transaction"
projects
Array of integers or null

List of projects id to get data by

object or null

A collection of filters used to segment experience report data based on various visitor attributes and traffic sources. Applying these filters allows for deeper analysis of how different user groups interact with experience variations. Knowledge Base: "Using Basic and Advanced Post segmentation".

expand
Array of strings or null (LiveDataExpandFields)
Enum: "custom_segments" "experiences" "experiences.variation" "conversion.goals" "project"

Specifies linked objects to expand in the live data response. Refer to the Expanding Fields section.

Responses

Request samples

Content type
application/json
{
  • "event_types": [
    ],
  • "projects": [
    ],
  • "segments": {
    },
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get change history for an account

Retrieves a historical log of changes made within the specified account, such as modifications to account settings or billing. This provides an audit trail for account-level activities. The Knowledge Base states, "The Change History shows a record of user activity for each of your projects." This extends to account changes.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

Request Body schema: application/json

Filters for retrieving the change history log for an account. Allows specifying date ranges, the user who made changes, types of objects changed (e.g., 'project', 'billing'), and methods of change (API or app UI).

onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

methods
Array of strings or null (ChangeHistoryMethods)
Enum: "api" "app"
projects
Array of integers or null

List of projects id to get data by

objects
Array of strings or null (ChangeHistoryObjectTypes)
Enum: "account" "audience" "feature" "collaborator" "domain" "goal" "hypothesis" "experience" "report" "change" "variation" "project" "tag"

List of objects to get data by

sort_by
string or null
Default: "timestamp"
Enum: "timestamp" "project_id" "event" "object"

A value to sort history list by specific field(s)

Defaults to timestamp if not provided

expand
Array of strings or null (ChangeHistoryExpandFields)
Value: "project"

Specifies linked objects to expand in the response, e.g., 'project'. Refer to the Expanding Fields section.

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "page": 1,
  • "sort_direction": "asc",
  • "results_per_page": 30,
  • "methods": [
    ],
  • "projects": [
    ],
  • "objects": [
    ],
  • "sort_by": "timestamp",
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

List active and completed experiences for an account

Retrieves a list of all active and completed experiences (A/B tests, personalizations, etc.) across all projects within the specified account. Allows filtering to narrow down results. Useful for an overview of ongoing and finished optimization activities at the account level.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

Request Body schema: application/json
onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
projects
Array of integers or null

Project IDs list to be used to filter experiences

sort_by
string or null
Default: "id"
Enum: "id" "conversions" "improvement" "name" "start_time" "end_time" "status" "project_id" "primary_goal"

A value used to sort experiences by specific field

Defaults to id if not provided

search
string or null

A search string that would be used to search against Experience's name and description

type
Array of strings or null (ExperienceTypes)
Enum: "a/b" "a/a" "mvt" "split_url" "multipage" "deploy" "a/b_fullstack" "feature_rollout"

The type of the experiences to be returned; either of the below can be provided

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

include
Array of strings (ExperienceIncludeFields)
Items Enum: "alerts" "goals" "stats" "variations" "variations.changes" "min_running_timestamp" "max_running_timestamp" "audiences" "locations" "collaborators"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

Read more in the section related to Optional Fields

expand
Array of strings (ExperienceExpandFields)
Items Enum: "project" "audiences" "goals" "locations" "variations" "variations.changes" "tags"

Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to Expanding Fields

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "projects": [
    ],
  • "sort_by": "id",
  • "search": "string",
  • "type": [
    ],
  • "page": 1,
  • "include": [
    ],
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific account

Retrieves detailed information about a specific account, including its settings, billing status, and usage limits. The include parameter can be used to fetch additional related data, like active project counts.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

query Parameters
include
Array of strings (AccountDetailsIncludeFields)
Items Enum: "stats" "settings.tracking_script.available_versions"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

Read more in the section related to Optional Fields

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update details for a specific account

Modifies the settings or billing information for a specific account. This can include updating company details, contact information, or billing preferences.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

Request Body schema: application/json

A JSON object containing the account details to be updated, such as company name, address, tax information, billing contact emails, or settings like allowing over-quota charges.

accountType
string

Defines the type of the account:

  • main: A primary account that can have sub-accounts and manages its own billing.
  • sub: A secondary account existing under a main account, often used by agencies to manage client activities. Sub-accounts share quotas from the parent.
name
string <= 200 characters

The user-defined, friendly name for the account (e.g., "Client X Marketing", "My Company Inc.").

object

Various Account level settings that can be controlled by the user

object

Billing related data and settings

Responses

Request samples

Content type
application/json
Example
{
  • "accountType": "main",
  • "name": "string",
  • "settings": {
    },
  • "billing": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a new sub-account

Creates a new sub-account under the specified parent main account. Sub-accounts inherit certain properties and limits from the parent but can have their own users and projects. This is typically used by agencies or larger organizations to manage client accounts or departmental usage separately.

path Parameters
account_id
required
integer

ID of the parent account under which the sub-account is being created.

Request Body schema: application/json

A JSON object with details for the new sub-account, including its name, the initial owner's name and email, and specific billing plan configurations and usage limits.

name
required
string <= 200 characters

The user-defined, friendly name for the account (e.g., "Client X Marketing", "My Company Inc.").

object

Various Account level settings that can be controlled by the user

required
object
userName
required
string

Name of the user that would own this account.

userEmail
required
string

Email of the user that would own this account. If the an user exists with that email, the respective user would be used. Otherwise, a new user would get created.

sendUserEmail
boolean
Default: false

Flag indicating whether an email to be sent or not to the user, notifying them that an account was created for them by main account.

An email with a complete sign-up link would be sent regardless if the user does not exist into the system and gets created.

customEmailText
string <= 1024 characters

Custom text to be appended to the email that gets sent to the user if sendUserEmail = true

Responses

Request samples

Content type
application/json
{
  • "accountType": "main",
  • "name": "string",
  • "settings": {
    },
  • "billing": {
    },
  • "userName": "string",
  • "userEmail": "string",
  • "sendUserEmail": false,
  • "customEmailText": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Request add-ons for an account

Allows requesting specific add-on features or services for an account, such as premium support tiers or specialized training.

path Parameters
account_id
required
integer

ID of the account for which the addons will be requested

Request Body schema: application/json

A JSON object specifying the addon being requested (e.g., 'one_time_convert_launch' for a managed service) and, if applicable, collaborator details for whom the add-on is intended.

addon
required
string (AccountAddonsTypes)
Enum: "one_time_convert_launch" "conversionXl_mini_course" "convert_remote_1h" "goodUi_annual_solo"
collaborator_email
string <= 100 characters

Email of the collaborator for whom the add-on is being requested (if applicable).

collaborator_name
string <= 200 characters

Name of the collaborator for whom the add-on is being requested (if applicable).

Responses

Request samples

Content type
application/json
{
  • "addon": "one_time_convert_launch",
  • "collaborator_email": "string",
  • "collaborator_name": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Initiate payment method setup

Starts a secure session with the payment provider (e.g., Stripe) to set up or update an account's payment method. Returns a client secret or token that the frontend UI uses to complete the payment setup process directly with the provider.

path Parameters
account_id
required
integer

ID of the account for which the payment setup will be started

Request Body schema: application/json

An optional JSON object, though typically empty for this request. The primary action is to initiate a secure session with the payment provider (e.g., Stripe) for adding or updating payment methods.

object or null (StartPaymentSetupRequestData)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "client_secret": "string"
}

Get users for billing plan setup notification

Retrieves a list of users associated with an account, typically for the purpose of notifying them about billing plan setup or changes. Used internally for account management workflows.

path Parameters
account_id
required
integer

ID of the account for which the plan setup users will be returned

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

AI content

Generate text variations using AI

Leverages Generative AI to create alternative text versions (variants) for a given piece of content. Users can specify the number of variations, the original content, an AI model framework (e.g., Cialdini, AIDA), and a specific principle within that framework. This helps in quickly generating creative options for A/B testing headlines, calls to action, or other textual elements. Optionally, an OpenAI Key can be provided for using more advanced models or larger context.

path Parameters
account_id
required
integer

ID of the account under which the api call executes

Request Body schema: application/json
required
object

Parameters to customize the AI generation process.

content
required
string

The original text content (e.g., headline, call-to-action, product description) that you want the AI to rewrite or generate variations for.

openAI_Key
string

(Optional) Your OpenAI API key. Providing this may allow for using more advanced OpenAI models (e.g., GPT-4) or handling larger context_content, potentially leading to higher quality or more nuanced variations. If not provided, Convert's default AI capabilities will be used.

context_content
string

(Optional) Additional text to provide context to the AI model, helping it understand the subject matter, tone, or specific constraints for the generated variations. For example, you could provide the product page content if generating a headline for that product. If no openAI_Key is provided, this content may be trimmed to the first 200 words. When principle_class=none is provided, this field can be used for custom prompt instructions.

previousResponses
Array of strings

(Optional) A list of text strings representing previously generated AI variants for the same input content. Providing these helps the AI avoid generating duplicate or very similar suggestions, ensuring more diverse outputs if requesting variations iteratively.

principle_class
any

Framework model from which principles used for text generation are selected

Responses

Request samples

Content type
application/json
Example
{
  • "parameters": {
    },
  • "content": "string",
  • "openAI_Key": "string",
  • "context_content": "string",
  • "previousResponses": [
    ],
  • "principle_class": "none"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Collaborators

Convert Experiences organizes customer data into Accounts(which are billable entities) and gives Users access to accounts under different roles. By default the user that initially setups an account, will get access to that account as the owner of it. Other users can be invited to get access to specific/all projects inside that account becoming this way Collaborators of that Account

List users and their access permissions for an account

Retrieves a list of all users who have collaborator access to the specified account. For each user, it details the projects they can access and their role within those projects (e.g., Admin, Editor). The expand parameter can be used to get more details about the projects. As per the Knowledge Base, "Account owners can invite collaborators to projects and choose to give them varying privileges."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

query Parameters
expand
Array of strings (AccountUserAccessesExpandFields)
Items Value: "accesses.project"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update a user's access permissions for an account

Modifies the access rights of an existing collaborator for the specified account. This can involve changing their role for specific projects or altering which projects they can access. Identifies the user by user_id (for active collaborators) or email (for pending invitations).

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

Request Body schema: application/json

Contains the user identifier (either email for pending invitations or user_id for active collaborators) and the updated list of project accesses and their corresponding roles (e.g., 'admin', 'editor') for that user within the account.

Any of
user_id
string or null

The unique system identifier for an active Convert user. Null if the user is only an invitee (pending acceptance).

first_name
string <= 200 characters

Collaborator's first name

last_name
string <= 200 characters

Collaborator's last name

Array of objects

List of projects the user can access

custom_message
string <= 200 characters

(For invitations) A custom message to include in the invitation email sent to a new collaborator.

expand
Array of strings (AccountUserAccessesExpandFields)
Items Value: "accesses.project"

Specifies linked objects to expand in the response, e.g., 'accesses.project'. Refer to the Expanding Fields section.

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "accesses": [
    ],
  • "custom_message": "string",
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Invite a new collaborator to an account

Sends an invitation to a user (identified by email) to become a collaborator on the specified account. The request defines the initial set of projects and the role the user will have for those projects. The user will receive an email to accept the invitation.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

Request Body schema: application/json

Contains the invitee's email, first name, last name, and the initial list of project accesses and their roles. A custom message can be included in the invitation email.

first_name
string <= 200 characters

Collaborator's first name

last_name
string <= 200 characters

Collaborator's last name

required
Array of objects

List of projects the user can access

email
required
string <= 100 characters

The email address of the collaborator or invitee.

custom_message
string <= 200 characters

(For invitations) A custom message to include in the invitation email sent to a new collaborator.

expand
Array of strings (AccountUserAccessesExpandFields)
Items Value: "accesses.project"

Specifies linked objects to expand in the response, e.g., 'accesses.project'. Refer to the Expanding Fields section.

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "accesses": [
    ],
  • "email": "string",
  • "custom_message": "string",
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Remove a collaborator's access from an account

Revokes a user's collaborator access to specified projects within an account, or entirely from the account. Identifies the user by user_id or email.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

Request Body schema: application/json

Contains the user identifier (email or user_id) and a list of project accesses to be revoked for that user. If the list of accesses is empty, it might imply removing the user from all projects or the account entirely, depending on implementation.

One of
user_id
string or null

The unique system identifier for an active Convert user. Null if the user is only an invitee (pending acceptance).

Array of objects

A list defining the user's access to specific projects or all projects within the account. Each item specifies a project (ID or null for all projects) and the role granted.

Responses

Request samples

Content type
application/json
Example
{
  • "user_id": "string",
  • "accesses": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Check partner status for extended API access

Verifies if the provided email belongs to a registered partner, potentially enabling extended API functionalities. This is an internal mechanism.

Request Body schema: application/json

Contains the email address to check if it belongs to a registered Convert partner, for potential extended API access (internal use).

email
string <= 100 characters

The email address of the potential partner to verify.

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "email": "string",
  • "allowed": true,
  • "alreadyGranted": true
}

Accept a collaborator invitation

Allows a user to accept an invitation to collaborate on an account using a unique hash token received via email. If the user is new to Convert, this will also trigger account creation.

Request Body schema: application/json

Contains the unique hash token that a user received in an email invitation to collaborate on an account, used to accept the invitation.

hash
string <= 200 characters

The unique invitation token from the collaborator invitation email.

Responses

Request samples

Content type
application/json
{
  • "hash": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

API Keys

API Keys are used to authenticate requests from Server side applications that access this API

List API keys for an account

Retrieves a list of all API keys configured for the specified account. API keys are used for server-to-server authentication, allowing applications to interact with the Convert API programmatically. Each key can be scoped to specific projects.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a new API key for an account

Generates a new API key and secret for the specified account. The key can be named for easier identification and can be restricted to a list of project IDs. If no projects are specified, the key grants access to all projects in the account. The API secret is only shown at the time of creation and should be stored securely.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

Request Body schema: application/json

Contains the name for the new API key for easy identification, and an optional list of projects (by ID) to which this key will grant access. If projects is omitted, the key typically grants access to all projects in the account.

name
required
string <= 100 characters

A user-defined, friendly name for the API key to help identify its purpose or the application using it (e.g., "Reporting Dashboard Integration", "Nightly Data Sync Script").

auth_type
string
Default: "requestSigning"
Enum: "requestSigning" "secretKey"

The authentication type for this API key:

  • requestSigning: Each request must be signed with the key and a hash sent in the header (most secure)
  • secretKey: A simpler authentication method using the secret key as a Bearer token in the Authorization header (good security)
projects
Array of numbers or null

An optional list of project IDs that this API key is authorized to access. If null or an empty list, the key typically grants access to all projects within the account it belongs to. This allows for granular control over API key permissions.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "auth_type": "requestSigning",
  • "projects": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "auth_type": "requestSigning",
  • "projects": [
    ],
  • "key_id": "string",
  • "key_secret": "string"
}

Delete an API key

Permanently revokes an API key, identified by its key_id. Once deleted, the key can no longer be used to authenticate API requests.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

key_id
required
string

ID of the API key to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Projects

Once you start using Convert Experiences, you will have a growing number of experiences to manage. Projects help you keep everything organized across multiple sites. Each project has its own tracking code, set of experiences, and set of collaborators. For example, if you run experiences on multiple domains, you can assign a unique project for each domain. Read here some things you need to know about how a project behaves.

List projects within an account

Retrieves a list of all projects belonging to the specified account that the authenticated user has access to. Supports filtering by project status, name/description search, and pagination. A project in Convert is a container for organizing experiences (A/B tests, personalizations), goals, audiences, and associated domains. As per the Knowledge Base: "Each project has its own tracking code, set of experiences, and set of collaborators."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

Request Body schema: application/json

Optional filters for listing projects. You can search by name or description, filter by status (active/inactive), project_type (web/fullstack), tracking_script_release_type, specific tracking_script_version, or use pagination (page, results_per_page). Also supports only and except for specific project IDs.

onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
status
Array of strings or null
Enum: "active" "inactive"

Filters projects by their status

search
string or null <= 200 characters

A search string that would be used to search against Project's name and description

legacy_script
boolean or null
Enum: true false

Filters projects based on whether they use the legacy script (true) or the new script (false).

tracking_script_release_type
Array of strings or null (TrackingScriptReleaseTypes)
Enum: "manual" "latest" "scheduled"

Filters projects by their tracking script release type.

object or null

Filters projects by their tracking script version.

only
Array of integers or null <= 100 items

Only retrieve projects with the given ids.

except
Array of integers <= 100 items

Except projects with the given ids.

sort_by
string or null
Default: "id"
Enum: "id" "active_tests" "project_name" "project_type" "status" "used_visitors"

A value to sort projects by specific field(s)

Defaults to id if not provided

project_type
Array of strings or null
Enum: "web" "fullstack"

Filters projects by their type.

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

include
Array of strings (ProjectsListIncludeField)
Items Enum: "global_javascript" "domains" "stats.usage" "stats.active_experiences_count" "stats.active_experiments_count" "stats.experiences_count" "stats.segments_count" "stats.active_segments_count" "stats.active_goals_count" "stats.google_analytics" "default_goals" "default_audiences" "default_locations" "settings.tracking_script.available_versions"

Specifies optional related data fields to include for each project in the list. Refer to the Optional Fields section.

expand
Array of strings (ProjectsListExpandFields)
Items Enum: "default_goals" "default_audiences" "default_locations"

Specifies linked objects to expand for each project in the list. Refer to the Expanding Fields section.

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "status": [
    ],
  • "search": "string",
  • "legacy_script": true,
  • "tracking_script_release_type": [
    ],
  • "tracking_script_version": {
    },
  • "only": [
    ],
  • "except": [
    ],
  • "sort_by": "id",
  • "project_type": [
    ],
  • "page": 1,
  • "include": [
    ],
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get change history for a specific project

Retrieves a historical log of changes made within a specific project. This includes modifications to experiences, goals, audiences, locations, and project settings. Provides an audit trail for project-level activities, filterable by date, user, and event type. The Knowledge Base states: "Convert logs most actions that can be made in a Project; for example: creating an experiment, modifying a variation, adding and removing audiences, and more."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

Request Body schema: application/json

Filters for retrieving the change history log for a specific project. Allows specifying date ranges, users, types of project entities changed (e.g., 'experience', 'goal', 'audience'), and methods of change.

onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

methods
Array of strings or null (ChangeHistoryMethods)
Enum: "api" "app"
objects
Array of strings or null (ChangeHistoryObjects)
Enum: "audience" "feature" "domain" "goal" "hypothesis" "experience" "tag" "location"
audiences
Array of integers or null <= 100 items

List of audiences id to get data by

goals
Array of integers or null <= 100 items

List of goals id to get data by

locations
Array of integers or null <= 100 items

List of locations id to get data by

hypotheses
Array of integers or null <= 100 items

List of hypotheses id to get data by

domains
Array of integers or null <= 100 items

List of domains id to get data by

tags
Array of integers or null <= 100 items

List of tags id to get data by

experiences
Array of integers or null <= 100 items

List of experiences id to get data by

sort_by
string or null
Default: "timestamp"
Enum: "timestamp" "project_id" "event" "object"

A value to sort history list by specific field(s)

Defaults to timestamp if not provided

expand
Array of strings or null (ChangeHistoryExpandFields)
Value: "project"

Specifies linked objects to expand in the response, e.g., 'project'. Refer to the Expanding Fields section.

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "page": 1,
  • "sort_direction": "asc",
  • "results_per_page": 30,
  • "methods": [
    ],
  • "objects": [
    ],
  • "audiences": [
    ],
  • "goals": [
    ],
  • "locations": [
    ],
  • "hypotheses": [
    ],
  • "domains": [
    ],
  • "tags": [
    ],
  • "experiences": [
    ],
  • "sort_by": "timestamp",
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific project

Retrieves comprehensive details for a single project, identified by its project_id. This includes its name, type (web or fullstack), global JavaScript, settings (like time zone, jQuery inclusion), integrations, and optionally, associated domains and usage statistics. The include parameter can fetch related data like domains or stats.usage. The expand parameter can provide full objects for linked entities.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

query Parameters
include
Array of strings (ProjectIncludeFields)
Items Enum: "global_javascript" "domains" "stats.usage" "stats.active_experiences_count" "stats.active_experiments_count" "stats.experiences_count" "stats.segments_count" "stats.active_segments_count" "stats.active_goals_count" "stats.google_analytics" "default_goals" "default_audiences" "default_locations" "settings.tracking_script.available_versions"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

Read more in the section related to Optional Fields

expand
Array of strings (ProjectExpandFields)
Items Enum: "default_goals" "default_audiences" "default_locations"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Responses

Response samples

Content type
application/json
{
  • "global_javascript": "string",
  • "name": "string",
  • "project_type": "web",
  • "reporting_settings": {
    },
  • "settings": {
    },
  • "integrations_settings": {
    },
  • "status": "active",
  • "custom_domain": {
    },
  • "environments": {
    },
  • "default_goals": [
    ],
  • "default_audiences": [
    ],
  • "default_locations": [
    ],
  • "id": 0,
  • "accessRole": "owner",
  • "owner_email": "string",
  • "account_id": 0,
  • "created_at": 0,
  • "modified_at": 0,
  • "tracking_snippet": "string",
  • "type": "own",
  • "stats": {
    },
  • "domains": [
    ],
  • "sdk_key": "string"
}

Create a new project

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

Request Body schema: application/json

Contains all necessary information to define a new project. This includes its name, project_type ('web' or 'fullstack'), initial domains (for web projects), and various settings like time_zone, global_javascript, reporting_settings (e.g. currency, outlier rules), and integrations_settings.

global_javascript
string or null

Custom JavaScript code that will be included on all pages where this project's tracking script is installed. This script runs before any experience-specific code, making it suitable for global helper functions, third-party integrations setup (like analytics), or defining global variables. KB: "Project, Experience, Variation Javascript" - "Global Project JavaScript".

name
required
string <= 200 characters

A user-defined, friendly name for the project (e.g., "Main Website Optimization", "Q3 Marketing Campaigns", "Mobile App Features").

project_type
string
Default: "web"
Enum: "web" "fullstack"

The type of project, determining its capabilities and how it's used:

  • web: For traditional website A/B testing, MVT, Split URL, personalization, and deploys using the client-side JavaScript tracking snippet.
  • fullstack: For server-side experiments, feature flagging, and mobile app testing using Convert's Full Stack SDKs. KB: "Full Stack Experiments on Convert".
object

Project settings used for reporting

object

General operational settings for the project.

object

Project-wide settings for various third-party integrations (e.g., Google Analytics, Crazy Egg, Hotjar). Experience-level settings can sometimes override these.

status
string (ProjectStatuses)
Enum: "active" "inactive" "suspended"

The overall status of a project:

  • active: The project is active, and experiences within it can run and track data.
  • inactive: The project is inactive (archived or paused). No experiences within it will run, and no new data will be tracked.
  • suspended: The project (or account) has been suspended, typically due to billing issues or terms of service violations. Services are disabled.
object or null

Configuration for using a custom domain (CNAME) to serve the Convert tracking script and receive tracking data. This can improve branding and potentially reduce issues with ad blockers or third-party cookie restrictions. Requires DNS setup.

object
Default: {"production":{"label":"Production","is_default":true}}

A user-defined map of environments for this project (e.g., "production", "staging", "development"). Each environment has its own variant of the tracking script. Experiences are typically configured to run in a specific environment. The number of allowed environments depends on the account's subscription plan. KB: "The Environments Feature".

Array of integers or SimpleGoal (object) (SimpleGoalExpandable)

A list of Goal IDs that will be automatically added to any new experience created within this project.

Array of integers or SimpleAudience (object) (SimpleAudienceExpandable)

A list of Audience IDs that will be automatically added to any new experience created within this project.

Array of integers or SimpleLocation (object) (SimpleLocationExpandable)

A list of Location IDs that will be automatically added to any new experience created within this project.

Array of objects (DomainToCreate)

The list of websites included in this project.

include
Array of strings (ProjectsListIncludeField)
Items Enum: "global_javascript" "domains" "stats.usage" "stats.active_experiences_count" "stats.active_experiments_count" "stats.experiences_count" "stats.segments_count" "stats.active_segments_count" "stats.active_goals_count" "stats.google_analytics" "default_goals" "default_audiences" "default_locations" "settings.tracking_script.available_versions"

Specifies optional related data fields to include for each project in the list. Refer to the Optional Fields section.

expand
Array of strings (ProjectsListExpandFields)
Items Enum: "default_goals" "default_audiences" "default_locations"

Specifies linked objects to expand for each project in the list. Refer to the Expanding Fields section.

Responses

Request samples

Content type
application/json
{
  • "global_javascript": "string",
  • "name": "string",
  • "project_type": "web",
  • "reporting_settings": {
    },
  • "settings": {
    },
  • "integrations_settings": {
    },
  • "status": "active",
  • "custom_domain": {
    },
  • "environments": {
    },
  • "default_goals": [
    ],
  • "default_audiences": [
    ],
  • "default_locations": [
    ],
  • "domains": [
    ],
  • "include": [
    ],
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "global_javascript": "string",
  • "name": "string",
  • "project_type": "web",
  • "reporting_settings": {
    },
  • "settings": {
    },
  • "integrations_settings": {
    },
  • "status": "active",
  • "custom_domain": {
    },
  • "environments": {
    },
  • "default_goals": [
    ],
  • "default_audiences": [
    ],
  • "default_locations": [
    ],
  • "id": 0,
  • "accessRole": "owner",
  • "owner_email": "string",
  • "account_id": 0,
  • "created_at": 0,
  • "modified_at": 0,
  • "tracking_snippet": "string",
  • "type": "own",
  • "stats": {
    },
  • "domains": [
    ],
  • "sdk_key": "string"
}

Update an existing project

Modifies the settings of an existing project. This can include changing its name, global JavaScript, time zone, active domains, integration settings, or GDPR compliance options. The list of domains provided in the request will replace the existing list.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer
Request Body schema: application/json

Contains the fields of the project to be updated. Any domains provided will replace the existing list. Other modifiable fields include name, global_javascript, reporting_settings, settings (like time zone, jQuery inclusion, GDPR options), and integrations_settings.

global_javascript
string or null

Custom JavaScript code that will be included on all pages where this project's tracking script is installed. This script runs before any experience-specific code, making it suitable for global helper functions, third-party integrations setup (like analytics), or defining global variables. KB: "Project, Experience, Variation Javascript" - "Global Project JavaScript".

name
string <= 200 characters

A user-defined, friendly name for the project (e.g., "Main Website Optimization", "Q3 Marketing Campaigns", "Mobile App Features").

project_type
string
Default: "web"
Enum: "web" "fullstack"

The type of project, determining its capabilities and how it's used:

  • web: For traditional website A/B testing, MVT, Split URL, personalization, and deploys using the client-side JavaScript tracking snippet.
  • fullstack: For server-side experiments, feature flagging, and mobile app testing using Convert's Full Stack SDKs. KB: "Full Stack Experiments on Convert".
object

Project settings used for reporting

object

General operational settings for the project.

object

Project-wide settings for various third-party integrations (e.g., Google Analytics, Crazy Egg, Hotjar). Experience-level settings can sometimes override these.

status
string (ProjectStatuses)
Enum: "active" "inactive" "suspended"

The overall status of a project:

  • active: The project is active, and experiences within it can run and track data.
  • inactive: The project is inactive (archived or paused). No experiences within it will run, and no new data will be tracked.
  • suspended: The project (or account) has been suspended, typically due to billing issues or terms of service violations. Services are disabled.
object or null

Configuration for using a custom domain (CNAME) to serve the Convert tracking script and receive tracking data. This can improve branding and potentially reduce issues with ad blockers or third-party cookie restrictions. Requires DNS setup.

object
Default: {"production":{"label":"Production","is_default":true}}

A user-defined map of environments for this project (e.g., "production", "staging", "development"). Each environment has its own variant of the tracking script. Experiences are typically configured to run in a specific environment. The number of allowed environments depends on the account's subscription plan. KB: "The Environments Feature".

Array of integers or SimpleGoal (object) (SimpleGoalExpandable)

A list of Goal IDs that will be automatically added to any new experience created within this project.

Array of integers or SimpleAudience (object) (SimpleAudienceExpandable)

A list of Audience IDs that will be automatically added to any new experience created within this project.

Array of integers or SimpleLocation (object) (SimpleLocationExpandable)

A list of Location IDs that will be automatically added to any new experience created within this project.

Array of integers or DomainToCreate (object) (DomainExpandableRequest)

The list of domains included in this project. If a domain ID is provided, that domain will just be updated.

Otherwise the domain will be created.

Caution: Any domain not in the provided list would be deleted from the project

include
Array of strings (ProjectsListIncludeField)
Items Enum: "global_javascript" "domains" "stats.usage" "stats.active_experiences_count" "stats.active_experiments_count" "stats.experiences_count" "stats.segments_count" "stats.active_segments_count" "stats.active_goals_count" "stats.google_analytics" "default_goals" "default_audiences" "default_locations" "settings.tracking_script.available_versions"

Specifies optional related data fields to include for each project in the list. Refer to the Optional Fields section.

expand
Array of strings (ProjectsListExpandFields)
Items Enum: "default_goals" "default_audiences" "default_locations"

Specifies linked objects to expand for each project in the list. Refer to the Expanding Fields section.

Responses

Request samples

Content type
application/json
{
  • "global_javascript": "string",
  • "name": "string",
  • "project_type": "web",
  • "reporting_settings": {
    },
  • "settings": {
    },
  • "integrations_settings": {
    },
  • "status": "active",
  • "custom_domain": {
    },
  • "environments": {
    },
  • "default_goals": [
    ],
  • "default_audiences": [
    ],
  • "default_locations": [
    ],
  • "domains": [
    ],
  • "include": [
    ],
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "global_javascript": "string",
  • "name": "string",
  • "project_type": "web",
  • "reporting_settings": {
    },
  • "settings": {
    },
  • "integrations_settings": {
    },
  • "status": "active",
  • "custom_domain": {
    },
  • "environments": {
    },
  • "default_goals": [
    ],
  • "default_audiences": [
    ],
  • "default_locations": [
    ],
  • "id": 0,
  • "accessRole": "owner",
  • "owner_email": "string",
  • "account_id": 0,
  • "created_at": 0,
  • "modified_at": 0,
  • "tracking_snippet": "string",
  • "type": "own",
  • "stats": {
    },
  • "domains": [
    ],
  • "sdk_key": "string"
}

Delete a project

Permanently removes an existing project and all its associated data (experiences, goals, audiences, reports) from the specified account. This action is irreversible. The Knowledge Base warns: "When a project is deleted all data will be purged from our servers within 7 days and is unrecoverable after that time."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get live tracking events for a specific project

Retrieves the last 100 tracking events (e.g., experiment views, goal conversions) specifically for the given project. Useful for real-time monitoring of a single project's activity. Supports filtering by event types, experiences, and goals. As per the Knowledge Base: "Live Logs in Convert track how end users are interacting with web pages and experiments...at a project and experiment level in real time."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project for which live data is returned

Request Body schema: application/json

Optional filters for project-specific live data. You can specify experiences (by ID), event_types (view_experience, conversion, transaction), goals (by ID), or segments to narrow down the real-time event feed.

experiences
Array of integers or null

A list of Experience IDs to filter events for. Only events related to these experiences will be returned.

event_types
Array of strings or null (LiveDataEventTypes)
Enum: "view_experience" "conversion" "transaction"
goals
Array of integers or null <= 20 items

A list of Goal IDs to filter conversion/transaction events for.

object or null

A collection of filters used to segment experience report data based on various visitor attributes and traffic sources. Applying these filters allows for deeper analysis of how different user groups interact with experience variations. Knowledge Base: "Using Basic and Advanced Post segmentation".

expand
Array of strings or null (LiveDataExpandFields)
Enum: "custom_segments" "experiences" "experiences.variation" "conversion.goals" "project"

Specifies linked objects to expand in the live data response. Refer to the Expanding Fields section.

Responses

Request samples

Content type
application/json
{
  • "experiences": [
    ],
  • "event_types": [
    ],
  • "goals": [
    ],
  • "segments": {
    },
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update multiple projects at once

Allows for updating settings (like tracking script version) for multiple projects simultaneously within an account. Requires a list of project IDs and the settings to apply.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data.

Request Body schema: application/json

Contains a list of project ids and the settings (specifically tracking_script.current_version) to be applied to all specified projects. Useful for rolling out tracking script updates.

id
required
Array of integers (BulkProjectIds) [ 1 .. 100 ] items

A list of project unique numerical identifiers to be affected by a bulk operation.

object

Project settings to be updated across the specified projects.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ],
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Generate a debug token for a project

Creates a temporary debug token for a project. This token can be used with the Convert tracking script (e.g., via the convert-debug-token header or query parameter) to preview draft or paused experiences, or to force specific variations for QA purposes without affecting live experiment data. The token has a limited time-to-live (TTL).

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Export project data as JSON

Generates a JSON file containing all configuration data for a specific project. This includes its experiences, goals, audiences, locations, hypotheses, and project settings. Useful for backing up project configurations or migrating them to another Convert account or instance. The Knowledge Base mentions this feature for "Save and Migrate Project Settings" and "Template Creation".

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project

Request Body schema: application/json

Specifies which components of the project to include in the JSON export. You can choose to include/exclude the main project settings, and lists of specific experiences, audiences, locations, goals, or hypotheses by their IDs. Useful for backups or migrations.

includeProject
boolean
Default: true

If true (default), includes the main project settings and configurations in the export. If false, only selected sub-entities (experiences, goals, etc.) might be exported.

object (ProjectExportObject)

Defines filtering for a specific type of entity (e.g., experiences, goals) within a project export. Allows either an include list (only these IDs) or an exclude list (all IDs except these). If both are omitted, all items of that entity type are included.

object (ProjectExportObject)

Defines filtering for a specific type of entity (e.g., experiences, goals) within a project export. Allows either an include list (only these IDs) or an exclude list (all IDs except these). If both are omitted, all items of that entity type are included.

object (ProjectExportObject)

Defines filtering for a specific type of entity (e.g., experiences, goals) within a project export. Allows either an include list (only these IDs) or an exclude list (all IDs except these). If both are omitted, all items of that entity type are included.

object (ProjectExportObject)

Defines filtering for a specific type of entity (e.g., experiences, goals) within a project export. Allows either an include list (only these IDs) or an exclude list (all IDs except these). If both are omitted, all items of that entity type are included.

object (ProjectExportObject)

Defines filtering for a specific type of entity (e.g., experiences, goals) within a project export. Allows either an include list (only these IDs) or an exclude list (all IDs except these). If both are omitted, all items of that entity type are included.

Responses

Request samples

Content type
application/json
{
  • "includeProject": true,
  • "experiences": {
    },
  • "audiences": {
    },
  • "locations": {
    },
  • "goals": {
    },
  • "hypothesis": {
    }
}

Response samples

Content type
download/json
{ }

Import project data from a JSON file

Creates a new project or updates an existing one by importing data from a JSON file (previously exported from Convert). This allows for restoring backups or replicating project setups. The Knowledge Base mentions this for "Save and Migrate Project Settings" and "Template Creation".

path Parameters
account_id
required
integer

ID of the account where the project will be stored.

Request Body schema: multipart/form-data

Contains the JSON file (previously exported from Convert) with the project data to be imported. This is used for creating a new project from an export or updating an existing one.

file
required
string <json>

The JSON file containing project data to be imported.

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Import associated data into an existing project

Imports associated data (like experiences, goals, audiences) from a JSON file into an already existing project. This is useful for selectively adding or updating components within a project from an export. The Knowledge Base mentions "Selective Import/Export: Choose to export/import entire projects or only selected goals, audiences, and locations."

path Parameters
account_id
required
integer

ID of the account where the project is stored.

project_id
required
integer

ID of the project to which details will be attached.

Request Body schema: multipart/form-data

Contains the JSON file (previously exported from Convert) with the project data to be imported. This is used for creating a new project from an export or updating an existing one.

file
required
string <json>

The JSON file containing project data to be imported.

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "imported": {
    }
}

SDK Keys

List SDK keys for a project

Retrieves a list of SDK keys associated with a specific project. SDK keys are used by Convert's Full Stack SDKs (e.g., Node.js, JavaScript) to fetch experiment configurations and track events from server-side or client-side applications. Each key is tied to a specific environment within the project (e.g., production, staging).

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a new SDK key for a project

Generates a new SDK key and, optionally, a secret for a specified project and environment. This key is then used by the Convert SDKs to authenticate and fetch project configurations. If has_secret is true and no sdk_secret is provided, a secret will be auto-generated. The SDK secret (if generated) is only shown at the time of creation.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

Request Body schema: application/json

Contains the name for the new SDK key, the target environment (e.g., 'production', 'staging') it applies to, and a boolean has_secret indicating if an SDK secret should be generated for secure SDK authentication.

name
required
string <= 100 characters

A user-defined, friendly name for the SDK key to help identify its purpose or the application/service using it (e.g., "Production Backend API", "Staging iOS App").

environment
required
string

The specific environment within the Full Stack project that this SDK key is associated with (e.g., "production", "development", "staging"). The SDK will fetch configurations relevant to this environment. This must match one of the environments defined at the project level. KB: "The Environments Feature".

status
string (SdkKeyStatuses)
Default: "enabled"
Enum: "enabled" "disabled"

Indicates whether the SDK key is active and can be used for API authentication. When disabled, all requests using this key will be rejected.

has_secret
boolean
Default: true

Whether the SDK key should have a secret key. When true, a secret key will be generated and returned in the response.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "environment": "string",
  • "status": "enabled",
  • "has_secret": true
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "sdk_key": "string",
  • "sdk_secret": "string",
  • "environment": "string",
  • "status": "enabled"
}

Update SDK Key

Partially update an SDK key, modifying only the specific fields provided in the request.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

sdk_key
required
string

ID of the SDK key to update

Request Body schema: application/json

Payload to update an existing SDK key

name
string <= 100 characters

A user-defined, friendly name for the SDK key to help identify its purpose or the application/service using it (e.g., "Production Backend API", "Staging iOS App").

environment
string

The specific environment within the Full Stack project that this SDK key is associated with (e.g., "production", "development", "staging"). The SDK will fetch configurations relevant to this environment. This must match one of the environments defined at the project level. KB: "The Environments Feature".

status
string (SdkKeyStatuses)
Default: "enabled"
Enum: "enabled" "disabled"

Indicates whether the SDK key is active and can be used for API authentication. When disabled, all requests using this key will be rejected.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "environment": "string",
  • "status": "enabled"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "sdk_key": "string",
  • "sdk_secret": "string",
  • "environment": "string",
  • "status": "enabled"
}

Delete an SDK key

Permanently revokes an SDK key, identified by its sdk_key value. Once deleted, SDKs using this key will no longer be able to fetch configurations or track events for the associated project and environment.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

sdk_key
required
string

ID of the SDK key to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Experiences

Convert Experiences provides a couple different experiences types. A/B, Split URL, Multivariate (MVT), Deploys, A/A and Multi-page (funnel) testing. To learn more, see Six experience types in Convert Experiences.

List experiences within a project

Retrieves a list of all experiences (A/B tests, MVT, Split URL, Deployments, etc.) within a specific project. Supports filtering by status, type, tags, and other criteria. Pagination is also supported. The include parameter can fetch related data like variations or goals. The expand parameter can provide full objects for linked entities. The Knowledge Base article "The Experience Overview Screen" describes the UI equivalent.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
goal_id
integer or null

Goal ID to be used for fetching experience's stats. Only applicable for the experiences that have access to a report. Defaults to primary experience's goal if none given.

sort_by
string or null
Default: "id"
Enum: "id" "conversions" "improvement" "name" "start_time" "end_time" "status" "primary_goal" "key"

A value used to sort experiences by specific field

Defaults to id if not provided

search
string or null <= 200 characters

A search string that would be used to search against Experience's name and description

status
Array of strings or null (ExperienceStatuses)
Enum: "draft" "active" "paused" "completed" "scheduled" "archived" "deleted"

The status of the experiences to be returned; either of the below can be provided

type
Array of strings or null (ExperienceTypes)
Enum: "a/b" "a/a" "mvt" "split_url" "multipage" "deploy" "a/b_fullstack" "feature_rollout"

The type of the experiences to be returned; either of the below can be provided

tags
Array of integers or null

The list of tag ID's used to filter the list of returned experiences

audiences
Array of integers or null

The list of audience ID's used to filter the list of returned experiences

goals
Array of integers or null

The list of goal ID's used to filter the list of returned experiences

features
Array of integers or null

The list of feature ID's used to filter the list of returned experiences

hypotheses
Array of integers or null

The list of hypotheses ID's used to filter the list of returned experiences

locations
Array of integers or null

The list of location ID's used to filter the list of returned experiences

environments
Array of strings or null

The list of environments used to filter the list of returned experiences

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

include
Array of strings (ExperienceIncludeFields)
Items Enum: "alerts" "goals" "stats" "variations" "variations.changes" "min_running_timestamp" "max_running_timestamp" "audiences" "locations" "collaborators"

Specifies the list of fields to be included in the response, which otherwise would be not sent.

Read more in the section related to Optional Fields

expand
Array of strings (ExperienceExpandFields)
Items Enum: "project" "audiences" "goals" "locations" "variations" "variations.changes" "tags"

Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to Expanding Fields

only
Array of integers or null <= 100 items

Only retrieve experiences with the given ids.

except
Array of integers <= 100 items

Except experiences with the given ids.

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "goal_id": 0,
  • "sort_by": "id",
  • "search": "string",
  • "status": [
    ],
  • "type": [
    ],
  • "tags": [
    ],
  • "audiences": [
    ],
  • "goals": [
    ],
  • "features": [
    ],
  • "hypotheses": [
    ],
  • "locations": [
    ],
  • "environments": [
    ],
  • "page": 1,
  • "include": [
    ],
  • "expand": [
    ],
  • "only": [
    ],
  • "except": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific experience

Retrieves comprehensive details for a single experience, identified by its experience_id. This includes its configuration (name, type, URL, status), associated audiences, locations, goals, variations, and integration settings. The include and expand parameters allow fetching more detailed related data. The Knowledge Base article "Experience Summary" describes the UI equivalent of this data.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the experience to be retrieved

query Parameters
include
Array of strings (ExperienceIncludeFields)
Items Enum: "alerts" "goals" "stats" "variations" "variations.changes" "min_running_timestamp" "max_running_timestamp" "audiences" "locations" "collaborators"

Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default

Read more in the section related to Optional Fields

expand
Array of strings (ExperienceExpandFields)
Items Enum: "project" "audiences" "goals" "locations" "variations" "variations.changes" "tags"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

header Parameters
report_token
string

Token to access the experience report in read-only mode.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "project": 0,
  • "alerts": [
    ],
  • "collaborators": [
    ],
  • "audiences": [
    ],
  • "locations": [
    ],
  • "goals": [
    ],
  • "tags": [
    ],
  • "multipage_pages": [
    ],
  • "customizations": [
    ],
  • "stats": {
    },
  • "variations": [
    ],
  • "description": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "global_js": "string",
  • "global_css": "string",
  • "name": "string",
  • "key": "string",
  • "primary_goal": 0,
  • "objective": "string",
  • "settings": {
    },
  • "site_area": {
    },
  • "status": "draft",
  • "traffic_distribution": 100,
  • "type": "a/b",
  • "version": 0,
  • "integrations": [
    ],
  • "screenshots_info": [
    ],
  • "environments": [
    ],
  • "environment": "string"
}

Get experience details by its unique key

Retrieves comprehensive details for a single experience, identified by its user-defined experience_key instead of its numerical ID. This is useful when you have a human-readable key for an experience. Functionality and parameters are otherwise similar to getting an experience by ID.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_key
required
string

The key of the experience to be retrieved

query Parameters
include
Array of strings (ExperienceIncludeFields)
Items Enum: "alerts" "goals" "stats" "variations" "variations.changes" "min_running_timestamp" "max_running_timestamp" "audiences" "locations" "collaborators"

Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default

Read more in the section related to Optional Fields

expand
Array of strings (ExperienceExpandFields)
Items Enum: "project" "audiences" "goals" "locations" "variations" "variations.changes" "tags"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "project": 0,
  • "alerts": [
    ],
  • "collaborators": [
    ],
  • "audiences": [
    ],
  • "locations": [
    ],
  • "goals": [
    ],
  • "tags": [
    ],
  • "multipage_pages": [
    ],
  • "customizations": [
    ],
  • "stats": {
    },
  • "variations": [
    ],
  • "description": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "global_js": "string",
  • "global_css": "string",
  • "name": "string",
  • "key": "string",
  • "primary_goal": 0,
  • "objective": "string",
  • "settings": {
    },
  • "site_area": {
    },
  • "status": "draft",
  • "traffic_distribution": 100,
  • "type": "a/b",
  • "version": 0,
  • "integrations": [
    ],
  • "screenshots_info": [
    ],
  • "environments": [
    ],
  • "environment": "string"
}

Create a new experience

Creates a new experience (e.g., A/B test, Split URL test, MVT, Deploy, A/A test, Multi-page Funnel) within a project. Requires defining the experience name, type, status (usually 'draft'), and the URL for the Visual Editor or original page. Variations, audiences, locations, goals, and other settings can be specified during creation. The Knowledge Base article "Create a New Experience" outlines the UI process.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

query Parameters
include
Array of strings (ExperienceIncludeFields)
Items Enum: "alerts" "goals" "stats" "variations" "variations.changes" "min_running_timestamp" "max_running_timestamp" "audiences" "locations" "collaborators"

Specifies the list of optional objects which would be included in the response.

Read more in the section related to Expanding Fields

expand
Array of strings (ExperienceExpandFields)
Items Enum: "project" "audiences" "goals" "locations" "variations" "variations.changes" "tags"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
description
string <= 500 characters

An optional, detailed explanation of the experience's purpose, hypothesis, or specific changes being tested.

start_time
integer or null

Unix timestamp (UTC) indicating when the experience was first activated (status changed to 'active'). Null or 0 if the experience has never been started.

end_time
integer or null

Unix timestamp (UTC) indicating when the experience was last stopped (e.g., paused or completed). Null or 0 if the experience is currently active or has never been stopped.

global_js
string

Custom JavaScript code that will be executed for all visitors bucketed into this experience, before any variation-specific code is applied. Useful for setting up common functionalities or variables needed by multiple variations. KB: "Project, Experience, Variation Javascript" - "Global Experience JavaScript".

global_css
string

Custom CSS rules that will be applied for all visitors bucketed into this experience, before any variation-specific CSS. Useful for common styling adjustments needed across all variations.

name
required
string <= 100 characters

A user-defined, friendly name for the experience (e.g., "Homepage Headline Test", "Checkout Funnel Optimization Q3"). This name is prominent in the Convert UI and reports.

key
string <= 32 characters

A unique, machine-readable key or identifier for this experience within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference (e.g., in Full Stack SDKs or API calls). Example: "homepage_headline_test_q3".

primary_goal
integer

The ID of the main conversion goal this experience is intended to optimize. Performance against this primary goal often determines the "winner" of an A/B test and is highlighted in reports. KB: "Experiment Report" - "Primary Goal".

objective
string or null <= 5000 characters

A detailed statement outlining the objective of this experience. This often includes the hypothesis being tested, the problem it aims to solve, the proposed solution (the variations), and the expected impact on key metrics. Connects to the "Hypotheses (Compass)" feature.

object (ExperienceSettings)

Experience's settings list

object or null

(Deprecated) The legacy way to define on which pages the experience should run, using a set of include/exclude rules based on URL components or page tags. Modern experiences should use the locations array instead for more flexible targeting.

status
required
string (ExperienceStatuses)
Enum: "draft" "active" "paused" "completed" "scheduled" "archived" "deleted"
traffic_distribution
number decimal places <= 4 [ 0 .. 100 ]

The percentage of total eligible website traffic (matching audience and location criteria) that will be directed into this entire experience. For example, a value of 50 means 50% of eligible visitors will participate, while the other 50% will see the default website content and not be tracked for this experience. The traffic within the experience is then further split among its variations based on variations[].traffic_distribution. KB: "What is an Traffic Distribution?".

type
required
string (ExperienceTypes)
Enum: "a/b" "a/a" "mvt" "split_url" "multipage" "deploy" "a/b_fullstack" "feature_rollout"

The type of optimization activity:

  • a/b: Standard A/B test comparing an original page/element against one or more variations. Changes made via Visual Editor or code. KB: "What is an Experiment?".
  • a/a: Tests the original page against an identical copy of itself to validate tracking setup and ensure no inherent bias. KB: "A/A Experiments".
  • mvt: Multivariate test, testing combinations of changes across multiple sections of a page. KB: "Creating a Multivariate Experiment".
  • split_url: Redirects traffic between different URLs to test entirely different page versions. KB: "How do Split URL Experiments work?".
  • multipage: Tests a consistent set of changes across a sequence of pages (funnel). KB: "Create Multipage Experiences".
  • deploy: Rolls out a specific set of changes to a targeted audience without A/B comparison reporting. KB: "What about Deployments?".
  • a/b_fullstack: An A/B test conducted using a Full Stack SDK, potentially involving server-side changes. KB: "Full Stack Experiments on Convert".
  • feature_rollout: A Full Stack experience for gradually rolling out a new feature, often using feature flags.
url
required
string <uri> <= 2048 characters

The primary URL used to load the page in Convert's Visual Editor when creating or editing this experience's variations. For Split URL tests, this is typically the URL of the original (control) page.

version
number

An internal version number for the experience, incremented upon certain modifications.

Array of ExperienceIntegrationBaidu (object) or ExperienceIntegrationClicktale (object) or ExperienceIntegrationClicky (object) or ExperienceIntegrationCnzz (object) or ExperienceIntegrationCrazyegg (object) or ExperienceIntegrationEconda (object) or ExperienceIntegrationEulerian (object) or ExperienceIntegrationGoogleAnalytics (any) or ExperienceIntegrationGosquared (object) or ExperienceIntegrationHeapanalytics (object) or ExperienceIntegrationHotjar (object) or ExperienceIntegrationMixpanel (object) or ExperienceIntegrationMouseflow (object) or ExperienceIntegrationPiwik (object) or ExperienceIntegrationSegmentio (object) or ExperienceIntegrationSitecatalyst (object) or ExperienceIntegrationWoopra (object) or ExperienceIntegrationYsance (object)

A list of configurations for third-party integrations enabled for this experience (e.g., Google Analytics, Hotjar, Mixpanel). Each object specifies the provider and any provider-specific settings (like a GA Custom Dimension index).

environments
Array of strings
Deprecated

(Deprecated) List of environment names where this experience will run. Use the singular environment field instead.

environment
string

The specific environment (e.g., "production", "staging", "development") within the project where this experience is intended to run. This must match one of the environments defined at the project level. If not set, it typically defaults to the project's default environment (often "production"). KB: "The Environments Feature".

Array of objects (MultipageExperiencePage)

An array of page objects, each with an id (unique within this experience, e.g., 'p1'), name, and url. Changes for each of these pages are then defined within the changes array of each variation, referencing the page_id. When updating, this list replaces all existing pages; pages not in the list will be removed.

audiences
Array of integers (ExperienceCreateUpdateAudiences)

A list of Audience IDs to associate with the experience. Visitors must match criteria from these audiences (according to settings.matching_options.audiences) to be eligible.

locations
Array of integers (ExperienceCreateUpdateLocations)

A list of Location IDs to associate with the experience. The experience will run on pages/conditions defined by these locations (according to settings.matching_options.locations).

goals
Array of integers (ExperienceCreateUpdateGoals)

A list of Goal IDs to attach to the experience for conversion tracking. The first goal in this list is often implicitly considered the primary_goal unless explicitly set otherwise. Not applicable for 'deploy' type experiences.

Array of integers or TagToCreate (object) (TagExpandableRequest)

The list of tags connected to this experience

Array of objects (ExperienceUserCustomizations) <= 100 items

A list of user-defined key-value pairs for customizing UI elements or behavior related to this experience within the Convert application itself. These do not affect the live experiment seen by visitors.

Array of objects (ExperienceVariationCreate)

The list of variations of this experience Note: This list is final, any variations not passed in the list which were previously connected to the experience will get deleted

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "global_js": "string",
  • "global_css": "string",
  • "name": "string",
  • "key": "string",
  • "primary_goal": 0,
  • "objective": "string",
  • "settings": {
    },
  • "site_area": {
    },
  • "status": "draft",
  • "traffic_distribution": 100,
  • "type": "a/b",
  • "version": 0,
  • "integrations": [
    ],
  • "environments": [
    ],
  • "environment": "string",
  • "multipage_pages": [
    ],
  • "audiences": [
    ],
  • "locations": [
    ],
  • "goals": [
    ],
  • "tags": [
    ],
  • "customizations": [
    ],
  • "variations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "project": 0,
  • "alerts": [
    ],
  • "collaborators": [
    ],
  • "audiences": [
    ],
  • "locations": [
    ],
  • "goals": [
    ],
  • "tags": [
    ],
  • "multipage_pages": [
    ],
  • "customizations": [
    ],
  • "stats": {
    },
  • "variations": [
    ],
  • "description": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "global_js": "string",
  • "global_css": "string",
  • "name": "string",
  • "key": "string",
  • "primary_goal": 0,
  • "objective": "string",
  • "settings": {
    },
  • "site_area": {
    },
  • "status": "draft",
  • "traffic_distribution": 100,
  • "type": "a/b",
  • "version": 0,
  • "integrations": [
    ],
  • "screenshots_info": [
    ],
  • "environments": [
    ],
  • "environment": "string"
}

Clone an existing experience

Creates a new experience as an identical copy of an existing one (specified by experience_id). This is useful for iterating on a previous test or using an existing experience as a template. The cloned experience starts in 'draft' status and does not copy historical report data. The Knowledge Base article "How to Clone an Experiment?" describes this.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the experience to be cloned

query Parameters
include
Array of strings (ExperienceIncludeFields)
Items Enum: "alerts" "goals" "stats" "variations" "variations.changes" "min_running_timestamp" "max_running_timestamp" "audiences" "locations" "collaborators"

Specifies the list of optional objects which would be included in the response.

Read more in the section related to Expanding Fields

expand
Array of strings (ExperienceExpandFields)
Items Enum: "project" "audiences" "goals" "locations" "variations" "variations.changes" "tags"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
name
string <= 100 characters

(Optional) A new name for the cloned experience. If not provided, the name will be based on the original (e.g., "Copy of [Original Name]").

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "project": 0,
  • "alerts": [
    ],
  • "collaborators": [
    ],
  • "audiences": [
    ],
  • "locations": [
    ],
  • "goals": [
    ],
  • "tags": [
    ],
  • "multipage_pages": [
    ],
  • "customizations": [
    ],
  • "stats": {
    },
  • "variations": [
    ],
  • "description": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "global_js": "string",
  • "global_css": "string",
  • "name": "string",
  • "key": "string",
  • "primary_goal": 0,
  • "objective": "string",
  • "settings": {
    },
  • "site_area": {
    },
  • "status": "draft",
  • "traffic_distribution": 100,
  • "type": "a/b",
  • "version": 0,
  • "integrations": [
    ],
  • "screenshots_info": [
    ],
  • "environments": [
    ],
  • "environment": "string"
}

Update an existing experience

Modifies the configuration of an existing experience. This can include changing its name, description, status (e.g., from 'draft' to 'active', or 'active' to 'paused'), URL, traffic distribution, audiences, locations, goals, variations, and integration settings. The Knowledge Base article "How Can I Change Variations After Experiment Started?" notes that variations cannot be added/removed after start, but other settings can be updated.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the updated experience

query Parameters
include
Array of strings (ExperienceIncludeFields)
Items Enum: "alerts" "goals" "stats" "variations" "variations.changes" "min_running_timestamp" "max_running_timestamp" "audiences" "locations" "collaborators"

Specifies the list of optional objects which would be included in the response.

Read more in the section related to Expanding Fields

expand
Array of strings (ExperienceExpandFields)
Items Enum: "project" "audiences" "goals" "locations" "variations" "variations.changes" "tags"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
description
string <= 500 characters

An optional, detailed explanation of the experience's purpose, hypothesis, or specific changes being tested.

start_time
integer or null

Unix timestamp (UTC) indicating when the experience was first activated (status changed to 'active'). Null or 0 if the experience has never been started.

end_time
integer or null

Unix timestamp (UTC) indicating when the experience was last stopped (e.g., paused or completed). Null or 0 if the experience is currently active or has never been stopped.

global_js
string

Custom JavaScript code that will be executed for all visitors bucketed into this experience, before any variation-specific code is applied. Useful for setting up common functionalities or variables needed by multiple variations. KB: "Project, Experience, Variation Javascript" - "Global Experience JavaScript".

global_css
string

Custom CSS rules that will be applied for all visitors bucketed into this experience, before any variation-specific CSS. Useful for common styling adjustments needed across all variations.

name
string <= 100 characters

A user-defined, friendly name for the experience (e.g., "Homepage Headline Test", "Checkout Funnel Optimization Q3"). This name is prominent in the Convert UI and reports.

key
string <= 32 characters

A unique, machine-readable key or identifier for this experience within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference (e.g., in Full Stack SDKs or API calls). Example: "homepage_headline_test_q3".

primary_goal
integer

The ID of the main conversion goal this experience is intended to optimize. Performance against this primary goal often determines the "winner" of an A/B test and is highlighted in reports. KB: "Experiment Report" - "Primary Goal".

objective
string or null <= 5000 characters

A detailed statement outlining the objective of this experience. This often includes the hypothesis being tested, the problem it aims to solve, the proposed solution (the variations), and the expected impact on key metrics. Connects to the "Hypotheses (Compass)" feature.

object (ExperienceSettings)

Experience's settings list

object or null

(Deprecated) The legacy way to define on which pages the experience should run, using a set of include/exclude rules based on URL components or page tags. Modern experiences should use the locations array instead for more flexible targeting.

status
string (ExperienceStatuses)
Enum: "draft" "active" "paused" "completed" "scheduled" "archived" "deleted"
traffic_distribution
number decimal places <= 4 [ 0 .. 100 ]

The percentage of total eligible website traffic (matching audience and location criteria) that will be directed into this entire experience. For example, a value of 50 means 50% of eligible visitors will participate, while the other 50% will see the default website content and not be tracked for this experience. The traffic within the experience is then further split among its variations based on variations[].traffic_distribution. KB: "What is an Traffic Distribution?".

type
string (ExperienceTypes)
Enum: "a/b" "a/a" "mvt" "split_url" "multipage" "deploy" "a/b_fullstack" "feature_rollout"

The type of optimization activity:

  • a/b: Standard A/B test comparing an original page/element against one or more variations. Changes made via Visual Editor or code. KB: "What is an Experiment?".
  • a/a: Tests the original page against an identical copy of itself to validate tracking setup and ensure no inherent bias. KB: "A/A Experiments".
  • mvt: Multivariate test, testing combinations of changes across multiple sections of a page. KB: "Creating a Multivariate Experiment".
  • split_url: Redirects traffic between different URLs to test entirely different page versions. KB: "How do Split URL Experiments work?".
  • multipage: Tests a consistent set of changes across a sequence of pages (funnel). KB: "Create Multipage Experiences".
  • deploy: Rolls out a specific set of changes to a targeted audience without A/B comparison reporting. KB: "What about Deployments?".
  • a/b_fullstack: An A/B test conducted using a Full Stack SDK, potentially involving server-side changes. KB: "Full Stack Experiments on Convert".
  • feature_rollout: A Full Stack experience for gradually rolling out a new feature, often using feature flags.
url
string <uri> <= 2048 characters

The primary URL used to load the page in Convert's Visual Editor when creating or editing this experience's variations. For Split URL tests, this is typically the URL of the original (control) page.

version
number

An internal version number for the experience, incremented upon certain modifications.

Array of ExperienceIntegrationBaidu (object) or ExperienceIntegrationClicktale (object) or ExperienceIntegrationClicky (object) or ExperienceIntegrationCnzz (object) or ExperienceIntegrationCrazyegg (object) or ExperienceIntegrationEconda (object) or ExperienceIntegrationEulerian (object) or ExperienceIntegrationGoogleAnalytics (any) or ExperienceIntegrationGosquared (object) or ExperienceIntegrationHeapanalytics (object) or ExperienceIntegrationHotjar (object) or ExperienceIntegrationMixpanel (object) or ExperienceIntegrationMouseflow (object) or ExperienceIntegrationPiwik (object) or ExperienceIntegrationSegmentio (object) or ExperienceIntegrationSitecatalyst (object) or ExperienceIntegrationWoopra (object) or ExperienceIntegrationYsance (object)

A list of configurations for third-party integrations enabled for this experience (e.g., Google Analytics, Hotjar, Mixpanel). Each object specifies the provider and any provider-specific settings (like a GA Custom Dimension index).

environments
Array of strings
Deprecated

(Deprecated) List of environment names where this experience will run. Use the singular environment field instead.

environment
string

The specific environment (e.g., "production", "staging", "development") within the project where this experience is intended to run. This must match one of the environments defined at the project level. If not set, it typically defaults to the project's default environment (often "production"). KB: "The Environments Feature".

Array of objects (MultipageExperiencePage)

An array of page objects, each with an id (unique within this experience, e.g., 'p1'), name, and url. Changes for each of these pages are then defined within the changes array of each variation, referencing the page_id. When updating, this list replaces all existing pages; pages not in the list will be removed.

audiences
Array of integers (ExperienceCreateUpdateAudiences)

A list of Audience IDs to associate with the experience. Visitors must match criteria from these audiences (according to settings.matching_options.audiences) to be eligible.

locations
Array of integers (ExperienceCreateUpdateLocations)

A list of Location IDs to associate with the experience. The experience will run on pages/conditions defined by these locations (according to settings.matching_options.locations).

goals
Array of integers (ExperienceCreateUpdateGoals)

A list of Goal IDs to attach to the experience for conversion tracking. The first goal in this list is often implicitly considered the primary_goal unless explicitly set otherwise. Not applicable for 'deploy' type experiences.

Array of integers or TagToCreate (object) (TagExpandableRequest)

The list of tags connected to this experience

Array of objects (ExperienceUserCustomizations) <= 100 items

A list of user-defined key-value pairs for customizing UI elements or behavior related to this experience within the Convert application itself. These do not affect the live experiment seen by visitors.

Array of objects (ExperienceVariationUpdate)

The list of variations of this experience

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "global_js": "string",
  • "global_css": "string",
  • "name": "string",
  • "key": "string",
  • "primary_goal": 0,
  • "objective": "string",
  • "settings": {
    },
  • "site_area": {
    },
  • "status": "draft",
  • "traffic_distribution": 100,
  • "type": "a/b",
  • "version": 0,
  • "integrations": [
    ],
  • "environments": [
    ],
  • "environment": "string",
  • "multipage_pages": [
    ],
  • "audiences": [
    ],
  • "locations": [
    ],
  • "goals": [
    ],
  • "tags": [
    ],
  • "customizations": [
    ],
  • "variations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "project": 0,
  • "alerts": [
    ],
  • "collaborators": [
    ],
  • "audiences": [
    ],
  • "locations": [
    ],
  • "goals": [
    ],
  • "tags": [
    ],
  • "multipage_pages": [
    ],
  • "customizations": [
    ],
  • "stats": {
    },
  • "variations": [
    ],
  • "description": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "global_js": "string",
  • "global_css": "string",
  • "name": "string",
  • "key": "string",
  • "primary_goal": 0,
  • "objective": "string",
  • "settings": {
    },
  • "site_area": {
    },
  • "status": "draft",
  • "traffic_distribution": 100,
  • "type": "a/b",
  • "version": 0,
  • "integrations": [
    ],
  • "screenshots_info": [
    ],
  • "environments": [
    ],
  • "environment": "string"
}

Delete an experience

Permanently removes an existing experience and all its associated data from the project. This action is irreversible. It's generally recommended to archive experiences instead of deleting them to preserve historical data. The Knowledge Base article "How Do I Archive / Delete an Experience?" highlights this.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience to be delete

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Manage report access token for an experience

Generates, regenerates, or deletes a unique token that allows read-only access to an experience's report. This is useful for sharing report data with stakeholders who do not have a Convert account or full project access. The token has an expiration time.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the Experience

Request Body schema: application/json
token_action
string
Enum: "regenerate" "delete"

The action to perform on the report token. If omitted, the current token (if valid) is returned, or a new one is generated if none exists or the old one expired.

token_expiration
integer [ 1 .. 48 ]

The desired expiration time for a new or regenerated token, in hours from the current time. If not provided when generating a token, a default expiration (e.g., 24 hours) is used.

Responses

Request samples

Content type
application/json
{
  • "token_action": "regenerate",
  • "token_expiration": 1
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "token": "string",
  • "expiration": 0
}

Get live tracking events for a specific experience

Retrieves the last 100 tracking events (views, conversions, revenue) specifically for the given experience. Useful for real-time monitoring and QA of a single active experience. Supports filtering by event type and goals. The Knowledge Base article "Live Logs for Projects and Experiments in Convert" describes this feature.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the experience is stored

experience_id
required
integer

ID of the Experience

Request Body schema: application/json

Optional filters for experience live data, such as specific goal IDs or event types to include in the feed.

event_types
Array of strings or null (LiveDataEventTypes)
Enum: "view_experience" "conversion" "transaction"
goals
Array of integers or null <= 20 items

A list of Goal IDs to filter conversion/transaction events for.

object or null

A collection of filters used to segment experience report data based on various visitor attributes and traffic sources. Applying these filters allows for deeper analysis of how different user groups interact with experience variations. Knowledge Base: "Using Basic and Advanced Post segmentation".

expand
Array of strings or null (LiveDataExpandFields)
Enum: "custom_segments" "experiences" "experiences.variation" "conversion.goals" "project"

Specifies linked objects to expand in the live data response. Refer to the Expanding Fields section.

Responses

Request samples

Content type
application/json
{
  • "event_types": [
    ],
  • "goals": [
    ],
  • "segments": {
    },
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get change history for a specific experience

Retrieves a historical log of all changes made to a specific experience. This includes modifications to its settings, variations, audiences, goals, status, etc. Provides an audit trail for the lifecycle of an experience, filterable by date and user. The Knowledge Base article "Track User Changes with Change History" details this.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the Experience

Request Body schema: application/json

Filters for retrieving the change history of a specific experience. Allows specifying date ranges, users, types of experience components changed (e.g., 'variation', 'goal', 'audience_linkage'), and methods of change.

onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

methods
Array of strings or null (ChangeHistoryMethods)
Enum: "api" "app"
objects
Array of strings or null (ExperienceHistoryObjects)
Enum: "report" "variation" "change"
sort_by
string or null
Default: "timestamp"
Enum: "timestamp" "event" "object"

A value to sort history list by specific field(s)

Defaults to timestamp if not provided

variations
Array of numbers or null <= 100 items

List of variations ids

changes
Array of numbers or null <= 100 items

List of changes ids

author_id
string or null

The id of the author who made changes

expand
Array of strings or null (ChangeHistoryExpandFields)
Value: "project"

Specifies linked objects to expand in the response, e.g., 'project'. Refer to the Expanding Fields section.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "methods": [
    ],
  • "objects": [
    ],
  • "sort_by": "timestamp",
  • "variations": [
    ],
  • "changes": [
    ],
  • "author_id": "string",
  • "expand": [
    ],
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "page": 1
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Trigger screenshot generation for experience variations

Initiates the process of generating or regenerating screenshots for the variations of a specified experience. These screenshots are displayed in the Convert UI to help visualize the changes made in each variation. The Knowledge Base article "Whitelist IPs for Screenshot Previews" is related as it lists IPs our service uses.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the Experience

Request Body schema: application/json
variations
Array of numbers

An optional list of specific variation IDs for which to generate/regenerate screenshots. If omitted, screenshots are triggered for all variations within the experience.

Responses

Request samples

Content type
application/json
{
  • "variations": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Update multiple experiences at once

Allows for changing the status (e.g., activate, pause, archive) of multiple experiences within a project simultaneously. Requires a list of experience IDs and the target status. The Knowledge Base article "Bulk Actions on Experiences" describes this UI feature.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json

Contains a list of experience ids and the target status (e.g., 'active', 'paused', 'archived') to apply to all of them. Useful for managing multiple experiments efficiently.

id
required
Array of integers (BulkExperienceIds) [ 1 .. 100 ] items

A list of unique numerical identifiers for experiences to be affected by a bulk operation.

status
required
string (BulkExperienceStatuses)
Enum: "active" "paused" "archived"

Responses

Request samples

Content type
application/json
{
  • "id": [
    ],
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Delete multiple experiences at once

Permanently removes multiple experiences from a project in a single operation. Requires a list of experience IDs. This action is irreversible. The Knowledge Base article "Bulk Actions on Experiences" describes this UI feature.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
id
required
Array of integers (BulkExperienceIds) [ 1 .. 100 ] items

A list of unique numerical identifiers for experiences to be affected by a bulk operation.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Experience Variations

Each Experience has one or more Variations which are presented to different groups of visitor in order to monitor the results of different changes or to personalize visitor's experience

Update an experience variation

Modifies an existing variation within an experience. This can include changing its name, description, traffic distribution, status (running/stopped), or the actual changes (CSS, JS, HTML modifications) it applies. The Knowledge Base article "How do I edit my variations?" covers the UI aspect.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the updated experience

variation_id
required
integer

The ID of the variation to be updated

Request Body schema: application/json
name
string <= 200 characters

A user-defined, friendly name for the variation (e.g., "Original Homepage", "Variation B - Green Button", "Personalized Offer for New Users"). This name appears in reports and the Convert UI.

description
string or null <= 2000 characters

An optional, more detailed explanation of what this variation entails or what changes it implements compared to the original or other variations.

is_baseline
boolean

If true, this variation is considered the baseline (control) against which other variations in the experience are compared for performance. Typically, the "Original" variation is the baseline. Only one variation per experience can be the baseline. Knowledge Base: "What is a Baseline?"

traffic_distribution
number decimal places <= 4 [ 0 .. 100 ]

The percentage of eligible traffic allocated to this specific variation. The sum of traffic_distribution for all active variations within an experience should ideally be 100% of the traffic allocated to the experience itself. For Multi-Armed Bandit (MAB) experiences, this value may be dynamically adjusted by the system. Knowledge Base: "What is an Traffic Distribution?"

key
string <= 32 characters

A unique, machine-readable key or identifier for this variation within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference (e.g., in Full Stack SDKs). Example: "control", "treatment_A".

status
string (ExperienceVariationStatuses)
Enum: "stopped" "running"
Array of ExperienceChangeId (object) or ExperienceChangeAdd (any) or ExperienceChangeUpdate (any)

An array of changes that this variation would apply. Empty array will remove changes.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "is_baseline": true,
  • "traffic_distribution": 100,
  • "key": "string",
  • "status": "stopped",
  • "changes": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "is_baseline": true,
  • "traffic_distribution": 100,
  • "key": "string",
  • "status": "stopped",
  • "changes": [
    ]
}

Delete an experience variation

Permanently removes a variation from an experience. Note: Deleting variations from an active or previously active experiment can impact statistical validity and is generally discouraged. It's often better to stop traffic to a variation. The Knowledge Base article "The Visual Editor in Convert Experiences" (Variations section) mentions: "You cannot delete a variation from an experience that is active or has been previously started and then paused."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the experience to which the variation belongs

variation_id
required
integer

The ID of the variation to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get screenshot for an experience variation

Retrieves the screenshot image for a specific variation, base64 encoded. Screenshots help visualize the changes applied by a variation and are shown in the Convert UI. Can request a full-size image or a thumbnail. The Knowledge Base article "Whitelist IPs for Screenshot Previews" is related.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the experience to which the variation belongs

variation_id
required
integer

The ID of the variation to be deleted

query Parameters
size
string
Value: "thumb"

The size of the returned image, if omitted will return full size

force_download
boolean

Flag used to force download instead of inline response

Responses

Response samples

Content type
application/json
{
  • "data": "string"
}

Upload a screenshot for an experience variation

Allows uploading a custom screenshot image for a specific variation. This can be useful if automatic screenshot generation fails or if a specific view needs to be captured. The uploaded image will be displayed in the Convert UI for this variation.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the experience to which the variation belongs

variation_id
required
integer

The ID of the variation to be deleted

query Parameters
size
string
Value: "thumb"

The size of the returned image, if omitted will return full size

force_download
boolean

Flag used to force download instead of inline response

Request Body schema: multipart/form-data
image
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "data": "string"
}

Convert a winning variation into a new experience (Deploy or A/B)

Takes a variation (often a winning one from an A/B test) and creates a new, separate experience from it. This new experience can be a 'Deploy' (to roll out the change to a specific audience) or another 'A/B' test (to further iterate). This is a common step after an A/B test concludes with a winner. The Knowledge Base article "What about Deployments?" mentions: "Create a new Deploy from a Variation or Winning Variation from another Experiment".

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the experience to which the variation belongs

variation_id
required
integer

The ID of the variation to be converted

Request Body schema: application/json
experience_type
string
Enum: "a/b" "deploy"

Type of the experience to be converted to

Responses

Request samples

Content type
application/json
{
  • "experience_type": "a/b"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "project": 0,
  • "alerts": [
    ],
  • "collaborators": [
    ],
  • "audiences": [
    ],
  • "locations": [
    ],
  • "goals": [
    ],
  • "tags": [
    ],
  • "multipage_pages": [
    ],
  • "customizations": [
    ],
  • "stats": {
    },
  • "variations": [
    ],
  • "description": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "global_js": "string",
  • "global_css": "string",
  • "name": "string",
  • "key": "string",
  • "primary_goal": 0,
  • "objective": "string",
  • "settings": {
    },
  • "site_area": {
    },
  • "status": "draft",
  • "traffic_distribution": 100,
  • "type": "a/b",
  • "version": 0,
  • "integrations": [
    ],
  • "screenshots_info": [
    ],
  • "environments": [
    ],
  • "environment": "string"
}

Experience Sections

Convert Experience's Sections provides API to update Sections of an experience.

List sections of a multivariate (MVT) experience

Retrieves the list of sections defined for a multivariate (MVT) experience. In MVT, a "section" is an element or area on the page where multiple alternatives (versions) are tested (e.g., a headline section with three different headline versions). Variations in an MVT are combinations of one version from each section. The Knowledge Base article "Creating a Multivariate Experiment" explains sections.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the experience of which to return sections list

query Parameters
include
Array of strings (ExperienceSectionIncludeFields)
Items Enum: "versions" "versions.changes"

Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default

Read more in the section related to Optional Fields

expand
Array of strings (ExperienceSectionIncludeFields)
Items Enum: "versions" "versions.changes"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Add a new section to an MVT experience

Creates a new section within a multivariate (MVT) experience. A section represents an element or area of the page to be tested with multiple alternatives (versions). Requires defining the section name and its initial versions with their respective changes.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the experience where section will be created

query Parameters
include
Array of strings (ExperienceSectionIncludeFields)
Items Enum: "versions" "versions.changes"

Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default

Read more in the section related to Optional Fields

expand
Array of strings (ExperienceSectionIncludeFields)
Items Enum: "versions" "versions.changes"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json

Defines a new section for a Multivariate (MVT) experience. Requires:

  • id: A unique 1-2 character ID for the section within this experience.
  • name: A descriptive name for the section (e.g., "Headline Area", "CTA Button Style").
  • versions: An array defining the initial alternatives (versions) for this section, each with its own set of changes. IMPORTANT: Adding or removing sections impacts MVT variation combinations and can invalidate running tests.
id
string [ 1 .. 2 ] characters ^[0-9a-z]{1,2}$

A unique identifier for this section within the MVT experience (e.g., "s1", "01", "ab"). Typically a short string (1-2 characters). This ID helps in structuring the MVT test.

name
string <= 200 characters

A user-defined, friendly name for this section (e.g., "Page Headline", "Main Call-to-Action Button", "Hero Image"). This name appears in MVT setup and reports.

required
Array of objects (SectionVersionCreate)

Version definition.

Each Multivariate experience is made of a list of Sections and a list of Versions

Than, variations of a Multivariate experience are made of all possible combinations of versions, takin one from each section.

Example: Experience has Section A and Section B. Section A has Version 1 and Version 2, Section B has Version 3 and Version 4

The resulting experience's variations will be the following:

  1. Section A - Version 1 + Section B - Version 3
  2. Section A - Version 2 + Section B - Version 3
  3. Section A - Version 1 + Section B - Version 4
  4. Section A - Version 1 + Section B - Version 4

Responses

Request samples

Content type
application/json
{
  • "id": "st",
  • "name": "string",
  • "versions": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update an existing section in an MVT experience

Modifies an existing section within a multivariate (MVT) experience. This can include changing the section's name or updating its versions and their associated changes. The entire list of versions for the section must be provided; versions not included will be removed.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the given experience

section_id
required
string

The ID of the updated section

query Parameters
include
Array of strings (ExperienceSectionIncludeFields)
Items Enum: "versions" "versions.changes"

Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default

Read more in the section related to Optional Fields

expand
Array of strings (ExperienceSectionIncludeFields)
Items Enum: "versions" "versions.changes"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json

Updates an existing section in an MVT experience. Requires the section's id and name. The versions array provided will replace all existing versions for this section. Each version object should include its id, name, and changes. If a version ID is new, it will be created. Existing versions not in the list will be removed. IMPORTANT: Modifying sections impacts MVT variation combinations.

id
string [ 1 .. 2 ] characters ^[0-9a-z]{1,2}$

A unique identifier for this section within the MVT experience (e.g., "s1", "01", "ab"). Typically a short string (1-2 characters). This ID helps in structuring the MVT test.

name
string <= 200 characters

A user-defined, friendly name for this section (e.g., "Page Headline", "Main Call-to-Action Button", "Hero Image"). This name appears in MVT setup and reports.

required
Array of objects (SectionVersionUpdate)

Version definition.

Each Multivariate experience is made of a list of Sections and a list of Versions

Than, variations of a Multivariate experience are made of all possible combinations of versions, takin one from each section.

Example: Experience has Section A and Section B. Section A has Version 1 and Version 2, Section B has Version 3 and Version 4

The resulting experience's variations will be the following:

  1. Section A - Version 1 + Section B - Version 3
  2. Section A - Version 2 + Section B - Version 3
  3. Section A - Version 1 + Section B - Version 4
  4. Section A - Version 1 + Section B - Version 4

Responses

Request samples

Content type
application/json
{
  • "id": "st",
  • "name": "string",
  • "versions": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Update all sections for an MVT experience

Replaces all existing sections and their versions for a multivariate (MVT) experience with the provided list. If a section or version from the existing configuration is not included in the request, it will be removed. The order of sections, versions, and changes is important and will be preserved. This is a comprehensive update for the entire MVT structure.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the exeprience for which to update sections

query Parameters
include
Array of strings (ExperienceSectionIncludeFields)
Items Enum: "versions" "versions.changes"

Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default

Read more in the section related to Optional Fields

expand
Array of strings (ExperienceSectionIncludeFields)
Items Enum: "versions" "versions.changes"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
Array of objects (UpdateSectionRequestData)

An array of UpdateSectionRequestData objects. Each object defines a section and its complete set of versions and changes.

  • To update an existing section, provide its id and modified name or versions.
  • To add a new section, provide a new unique id (1-2 chars), name, and its versions.
  • Sections from the current MVT configuration not present in this array will be deleted.

Responses

Request samples

Content type
application/json
{
  • "sections": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Section Versions

Convert Experience's Versions provides API to update Versions inside an experience's Section

Add a new version to an MVT section

Creates a new version (alternative) within a specific section of a multivariate (MVT) experience. Requires defining the version name and its associated changes (CSS, JS, etc.).

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the given experience

section_id
required
string

The ID of the section under which to create the version

query Parameters
include
Array of strings (ExperienceSectionVersionIncludeFields)
Items Value: "changes"

Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default

Read more in the section related to Optional Fields

expand
Array of strings (ExperienceSectionVersionExpandFields)
Items Value: "changes"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json

Adds a new version (alternative) to an existing section within an MVT experience. Requires:

  • id: A unique 1-2 character ID for this version within its section.
  • name: A descriptive name for the version (e.g., "Red Button", "Short Headline").
  • changes: An array defining the modifications (JS, CSS) for this specific version. IMPORTANT: Adding versions changes the MVT combinations.
id
string [ 1 .. 2 ] characters ^[0-9a-z]{1,2}$

A unique identifier for this version within its parent section (e.g., "v1", "02", "ab"). Typically a short string (1-2 characters). This ID is used to construct the overall MVT variation combinations.

name
string <= 200 characters

A user-defined, friendly name for this version (e.g., "Red Button", "Headline Option A", "Original Image"). This name appears in MVT setup and reports.

Array of ExperienceChangeAdd (any)

List of changes to apply. If ID of a change is not provided, the change is gonna be created. Otherwise the change would be updated

Responses

Request samples

Content type
application/json
{
  • "id": "st",
  • "name": "string",
  • "changes": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a version within an MVT section

Modifies an existing version within a specific section of a multivariate (MVT) experience. This can include changing the version's name or updating its associated changes.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the given experience

section_id
required
string

The ID of the section under which the updated version exists

version_id
required
string

The ID of the updated version

query Parameters
include
Array of strings (ExperienceSectionVersionIncludeFields)
Items Value: "changes"

Array parameter that would mention extra fields to be included into the response; otherwise those fields would be excluded by default

Read more in the section related to Optional Fields

expand
Array of strings (ExperienceSectionVersionExpandFields)
Items Value: "changes"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json

Updates an existing version within an MVT section. Allows changing the name or the changes (JS, CSS modifications) associated with this version. The id of the version must be provided.

id
string [ 1 .. 2 ] characters ^[0-9a-z]{1,2}$

A unique identifier for this version within its parent section (e.g., "v1", "02", "ab"). Typically a short string (1-2 characters). This ID is used to construct the overall MVT variation combinations.

name
string <= 200 characters

A user-defined, friendly name for this version (e.g., "Red Button", "Headline Option A", "Original Image"). This name appears in MVT setup and reports.

Array of ExperienceChangeId (object) or ExperienceChangeUpdate (any) or ExperienceChangeAdd (any)

List of changes to apply. If ID of a change is not provided, the change is gonna be created. Empty array will remove changes. Otherwise the change would be updated

Responses

Request samples

Content type
application/json
{
  • "id": "st",
  • "name": "string",
  • "changes": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a version from an MVT section

Permanently removes a version from a specific section of a multivariate (MVT) experience. Deleting versions can affect the combinations tested and the statistical validity of an active MVT.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

The ID of the given experience

section_id
required
string

The ID of the section under which the updated version exists

version_id
required
string

The ID of the updated version

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Version Changes

Each Experience's Variation has one or more Changes; a change represent the actual modification that is applied to a visitor. It can be a piece of javascript or CSS code for web experiences or it can be a string value for example in case of a fullstack experience.

Get details of a specific change in a variation

Retrieves the details of a single change applied within an experience's variation. A change can be CSS modifications, JavaScript code, HTML insertions, or configurations for Split URL redirects or Full Stack features. The data field structure depends on the type of the change.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience

change_id
required
integer

ID of the experience change to get/update

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "type": "richStructure",
  • "data": {
    }
}

Update a specific change in a variation

Modifies the content or settings of an existing change within an experience's variation. For example, updating the JavaScript code, CSS rules, or redirect pattern for a change. The structure of the data field in the request body must match the type of the change being updated.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience

change_id
required
integer

ID of the experience change to get/update

Request Body schema: application/json
One of
type
required
string
required
object

A flexible object containing the specific details and content for this change, structured according to the change type. For example, for customCode, it would contain js and css strings. For defaultRedirect, it would contain original_pattern and variation_pattern. This field is included by default when fetching a single ExperienceChange but might be omitted in list views unless specified in an include parameter.

Responses

Request samples

Content type
application/json
{
  • "type": "defaultCode",
  • "data": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "type": "richStructure",
  • "data": {
    }
}

Experiences Reports

Specification for different reports data that can be retrieved for experiences

Get report settings for an experience

Retrieves the specific reporting settings for an experience. This includes configurations like confidence level, statistical methodology (Frequentist/Bayesian), MAB strategy, primary metric, and outlier detection rules. These settings govern how experiment results are calculated and displayed. The Knowledge Base article "Experiment Report" (Stats Settings section) covers these.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience

header Parameters
report_token
string

Token to access the experience report in read-only mode.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get aggregated performance report for an experience

Retrieves the main performance report for a specific experience. This report shows aggregated data for each variation, including visitor counts, conversions, conversion rates, improvement percentages, and statistical confidence (or chance to win for Bayesian). Data is provided for all goals attached to the experience. Supports filtering by date range and segments. The Knowledge Base article "Experiment Report" details the metrics shown.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience

header Parameters
report_token
string

Token to access the experience report in read-only mode.

Request Body schema: application/json

Parameters to customize the aggregated performance report for an experience. Key parameters include:

  • start_time, end_time, utc_offset: Define the reporting period.
  • segments: Apply filters based on visitor characteristics (e.g., device, browser, country, custom segments).
  • stats_engine_processing: Configure statistical settings like confidence level, test type (one-tail/two-tails), MAB strategy, and MDE for Frequentist; or decision/risk thresholds for Bayesian.
  • goals: (Optional) List of specific goal IDs to include in the report. If omitted, all goals attached to the experience are reported.
  • metrics: (Optional) List of specific metrics (e.g., 'conversion_rate', 'avg_revenue_visitor') to calculate and display.
goals
Array of integers

A list of goal Id's for which to return the reporting data.

If no ID is provided, the list of goals attached to the experience is being used;

metrics
Array of strings (MetricTypes)
Items Enum: "conversion_rate" "avg_revenue_visitor" "avg_products_ordered_visitor"

The list of metrics to return. If not provided, all available metrics will be returned.

utc_offset
integer (UTC_Offset) [ -43200 .. 50400 ]
Default: 0

The time offset from Coordinated Universal Time (UTC) in seconds. For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200. Used for interpreting or displaying date/time information according to a specific timezone.

start_time
number or null

Unix timestamp (seconds since epoch) for the beginning of the reporting period. If null, data from the experience start is typically used. Should be interpreted with utc_offset.

end_time
number or null

Unix timestamp (seconds since epoch) for the end of thereporting period. If null, data up to the current time is typically used. Should be interpreted with utc_offset.

object (ReportingSegmentsFilters)

A collection of filters used to segment experience report data based on various visitor attributes and traffic sources. Applying these filters allows for deeper analysis of how different user groups interact with experience variations. Knowledge Base: "Using Basic and Advanced Post segmentation".

any (SE_ProcSettings)

Overall settings for the statistical engine processing results for this experience.

Responses

Request samples

Content type
application/json
{
  • "goals": [
    ],
  • "metrics": [
    ],
  • "utc_offset": 0,
  • "start_time": 0,
  • "end_time": 0,
  • "segments": {
    },
  • "stats_engine_processing": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get daily performance report for an experience

Retrieves a day-by-day breakdown of performance metrics (visitors, conversions, conversion rate, etc.) for a specific experience and goal. This allows trend analysis and observation of how an experiment performs over time. Supports filtering by date range and segments, and can show cumulative or non-cumulative data. The Knowledge Base article "Experiment Report" (Graphs section) visualizes this type of data.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience

header Parameters
report_token
string

Token to access the experience report in read-only mode.

Request Body schema: application/json

Parameters to customize the daily performance report. Requires:

  • goal: The ID of the specific goal for which daily data is requested.
  • report_type: 'cumulative' or 'non_cumulative' data.
  • metric: The primary metric for the daily report (e.g., 'conversion_rate', 'avg_revenue_per_visitor'). Also supports start_time, end_time, utc_offset, and segments for filtering.
goal
number

Goal's ID for which to return the reporting data

report_type
string (DailyReportTypes)
Enum: "cumulative" "non_cumulative"

Determines how daily data is aggregated in time-series reports.

metric
string (DailyReportMetrics)
Enum: "conversion_rate" "avg_revenue_per_visitor" "avg_products_ordered_per_visitor"

The specific performance metric to be displayed in a daily report.

object

A collection of filters used to segment experience report data based on various visitor attributes and traffic sources. Applying these filters allows for deeper analysis of how different user groups interact with experience variations. Knowledge Base: "Using Basic and Advanced Post segmentation".

utc_offset
integer (UTC_Offset) [ -43200 .. 50400 ]
Default: 0

The time offset from Coordinated Universal Time (UTC) in seconds. For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200. Used for interpreting or displaying date/time information according to a specific timezone.

start_time
number or null

Unix timestamp (seconds since epoch) for the beginning of the reporting period. If null, data from the experience start is typically used. Should be interpreted with utc_offset.

end_time
number or null

Unix timestamp (seconds since epoch) for the end of thereporting period. If null, data up to the current time is typically used. Should be interpreted with utc_offset.

any (SE_ProcSettings)

Overall settings for the statistical engine processing results for this experience.

Responses

Request samples

Content type
application/json
{
  • "goal": 0,
  • "report_type": "cumulative",
  • "metric": "conversion_rate",
  • "segments": {
    },
  • "utc_offset": 0,
  • "start_time": 0,
  • "end_time": 0,
  • "stats_engine_processing": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get daily traffic allocation report for an MAB experience

Retrieves the day-by-day traffic allocation percentages for each variation in an experience that uses Multi-Armed Bandit (MAB) or auto-allocation. This shows how Convert dynamically shifted traffic towards better-performing variations over time. The Knowledge Base article "Multi-Armed Bandit (MAB) & Auto-Allocation in Convert" explains this feature.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience

header Parameters
report_token
string

Token to access the experience report in read-only mode.

Request Body schema: application/json

Parameters to specify the date range (start_time, end_time, utc_offset) for retrieving the daily traffic allocation data, typically for experiences using Multi-Armed Bandit (MAB) strategies.

utc_offset
integer (UTC_Offset) [ -43200 .. 50400 ]
Default: 0

The time offset from Coordinated Universal Time (UTC) in seconds. For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200. Used for interpreting or displaying date/time information according to a specific timezone.

start_time
number or null

Unix timestamp (seconds since epoch) for the beginning of the reporting period. If null, data from the experience start is typically used. Should be interpreted with utc_offset.

end_time
number or null

Unix timestamp (seconds since epoch) for the end of thereporting period. If null, data up to the current time is typically used. Should be interpreted with utc_offset.

Responses

Request samples

Content type
application/json
{
  • "utc_offset": 0,
  • "start_time": 0,
  • "end_time": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Reset report data for an experience

Clears all accumulated visitor and conversion data for an experience's report, effectively resetting its statistics to zero. The start date of the experiment is also reset. This is useful if you want to restart data collection after making significant changes or for QA purposes. The Knowledge Base article "Reset Experiment Data" warns: "If you want to prevent [carry-over effects], it is suggested that you clone your experiment instead of resetting the report".

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Export an experience report (CSV/PDF)

Generates an export of an experience's performance report in either CSV (aggregated or daily) or PDF format. Returns a downloadable link for the generated file. Useful for offline analysis or sharing with stakeholders. The Knowledge Base article "Experiment Report" (Export & Download section) describes this.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience

Request Body schema: application/json

Parameters for exporting an experience report. Requires:

  • report_type: 'csv_aggregated' (summary data per variation) or 'csv_daily' (day-by-day data).
  • data_type: (For csv_daily only) 'cumulative' or 'non_cumulative'.
  • goals: (Optional) List of goal IDs to include. Also supports start_time, end_time, utc_offset, segments, and stats_engine_processing settings to match the online report.
report_type
string
Default: "csv_aggregated"
Enum: "csv_aggregated" "csv_daily"

Type of the exported report:

  • csv_aggregated - export in CSV format the number of visitors and metrics values aggregated per variation for the whole reported period
  • csv_daily - export in CSV format the number of visitors and metrics values per day, per variation for the whole reported period
data_type
string
Default: "non_cumulative"
Enum: "cumulative" "non_cumulative"

Type of data the exported report (csv_daily only)

goals
Array of integers

A list of goal Id's for which to return the reporting data.

If no ID is provided, the list of goals attached to the experience is being used.

Max 10 goals at one time available for csv_daily type.

utc_offset
integer (UTC_Offset) [ -43200 .. 50400 ]
Default: 0

The time offset from Coordinated Universal Time (UTC) in seconds. For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200. Used for interpreting or displaying date/time information according to a specific timezone.

start_time
number or null

Unix timestamp (seconds since epoch) for the beginning of the reporting period. If null, data from the experience start is typically used. Should be interpreted with utc_offset.

end_time
number or null

Unix timestamp (seconds since epoch) for the end of thereporting period. If null, data up to the current time is typically used. Should be interpreted with utc_offset.

object (ReportingSegmentsFilters)

A collection of filters used to segment experience report data based on various visitor attributes and traffic sources. Applying these filters allows for deeper analysis of how different user groups interact with experience variations. Knowledge Base: "Using Basic and Advanced Post segmentation".

any (SE_ProcSettings)

Overall settings for the statistical engine processing results for this experience.

Responses

Request samples

Content type
application/json
{
  • "report_type": "csv_aggregated",
  • "data_type": "cumulative",
  • "goals": [
    ],
  • "utc_offset": 0,
  • "start_time": 0,
  • "end_time": 0,
  • "segments": {
    },
  • "stats_engine_processing": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Export raw tracking data for an experience

Initiates a job to export the raw, event-level tracking data for a specific experience. This data includes individual visitor bucketing events, conversions, and transactions. The export is typically delivered as a link via email due to potential size. Useful for in-depth custom analysis or importing into external data warehouses. The Knowledge Base article "Experiment Report" (Export & Download section) mentions this.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience

Request Body schema: application/json

Parameters for requesting an export of raw, event-level tracking data. Requires:

  • events: List of event types to include (e.g., 'view_experience', 'conversion', 'transaction').
  • goals: (Optional) List of goal IDs to filter conversion/transaction events. Also supports start_time, end_time, utc_offset, and segments. The export is typically delivered via an emailed link.
events
Array of strings (ExportExperienceRawDataEvents)
Items Enum: "view_experience" "conversion" "transaction"

List of events to export

goals
Array of integers

A list of goal Id's for which to return the tracking data.

If no ID is provided, the list of goals attached to the experience is being used.

utc_offset
integer (UTC_Offset) [ -43200 .. 50400 ]
Default: 0

The time offset from Coordinated Universal Time (UTC) in seconds. For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200. Used for interpreting or displaying date/time information according to a specific timezone.

start_time
number or null

Unix timestamp (seconds since epoch) for the beginning of the reporting period. If null, data from the experience start is typically used. Should be interpreted with utc_offset.

end_time
number or null

Unix timestamp (seconds since epoch) for the end of thereporting period. If null, data up to the current time is typically used. Should be interpreted with utc_offset.

object (ReportingSegmentsFilters)

A collection of filters used to segment experience report data based on various visitor attributes and traffic sources. Applying these filters allows for deeper analysis of how different user groups interact with experience variations. Knowledge Base: "Using Basic and Advanced Post segmentation".

any (SE_ProcSettings)

Overall settings for the statistical engine processing results for this experience.

Responses

Request samples

Content type
application/json
{
  • "events": [
    ],
  • "goals": [
    ],
  • "utc_offset": 0,
  • "start_time": 0,
  • "end_time": 0,
  • "segments": {
    },
  • "stats_engine_processing": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Remove specific data from an experience report

Allows for targeted deletion of report data for an experience based on date range and event type (view_experience, conversion, transaction). For conversion and transaction events, specific goals can be targeted. If simulate is true, returns a count of records that would be deleted without actual deletion. Otherwise, performs permanent deletion. The Knowledge Base article "Remove Report Data Feature" details this.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

experience_id
required
integer

ID of the experience

Request Body schema: application/json

Parameters for removing specific data from an experience's report. Requires:

  • start_time, end_time: Defines the period for data deletion.
  • events: An array specifying the types of events to delete (e.g., 'view_experience', 'conversion', 'transaction'). For 'conversion' and 'transaction', specific goals can be targeted. For 'transaction', revenue_start_value and revenue_end_value can filter by revenue amount.
  • simulate: If true (default), returns a count of records that would be deleted. If false, performs permanent deletion. Also supports utc_offset and segments.
utc_offset
integer (UTC_Offset) [ -43200 .. 50400 ]
Default: 0

The time offset from Coordinated Universal Time (UTC) in seconds. For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200. Used for interpreting or displaying date/time information according to a specific timezone.

start_time
required
number or null

Unix timestamp (seconds since epoch) for the beginning of the reporting period. If null, data from the experience start is typically used. Should be interpreted with utc_offset.

end_time
required
number or null

Unix timestamp (seconds since epoch) for the end of thereporting period. If null, data up to the current time is typically used. Should be interpreted with utc_offset.

object (ReportingSegmentsFilters)

A collection of filters used to segment experience report data based on various visitor attributes and traffic sources. Applying these filters allows for deeper analysis of how different user groups interact with experience variations. Knowledge Base: "Using Basic and Advanced Post segmentation".

any (SE_ProcSettings)

Overall settings for the statistical engine processing results for this experience.

Array of RemoveExperienceReportEventTypeViewExperience (object) or RemoveExperienceReportEventTypeConversion (object) or RemoveExperienceReportEventTypeTransaction (object) non-empty

List of the events that would be targeted by the delete operation. If not provided, all the events would be targeted.

simulate
boolean
Default: true

When simulate - true is passed, it will only return back an object with the numbers of how many records will be deleted, instead of deleting any records

Responses

Request samples

Content type
application/json
{
  • "utc_offset": 0,
  • "start_time": 0,
  • "end_time": 0,
  • "segments": {
    },
  • "stats_engine_processing": {
    },
  • "events": [
    ],
  • "simulate": true
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Goals

Goals measure how well your site fulfills your target objectives. A goal represents a completed activity, called a conversion, that contributes to the success of your business. Examples of goals include making a purchase (for an ecommerce site), completing a game level (for a mobile gaming site), or submitting a contact information form (for a marketing or lead generation site). Read more information about Goals.

List goals within a project

Retrieves a list of all conversion goals defined for a specific project. Goals are used to measure the success of experiences (e.g., purchases, sign-ups, page views). Supports filtering by status, type, name, and pagination. The Knowledge Base article "Goals" describes various goal types like 'Visit a specific page', 'Revenue goal', 'Click on a link', etc.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
status
Array of strings or null (GoalStatuses)
Enum: "active" "archived"

List of goal statuses to be returned

is_default
boolean or null

A value that would be used to filter by default or not default goals. if not provided, all goals will be returned

search
string or null <= 200 characters

A search string that would be used to search against Goal's name and description

tracking
string or null
Enum: "tracked" "not_tracked" null

A value that would be used to filter by tracked or not tracked goals

usage
string or null
Enum: "used" "not_used" null

A value that would be used to filter by using in at least one experiment

goal_type
Array of strings or null (GoalTypes)
Enum: "advanced" "visits_page" "revenue" "clicks_link" "submits_form" "clicks_element" "dom_interaction" "scroll_percentage" "ga_import" "code_trigger"

List of goal types to be returned

experiences
Array of integers or null <= 100 items

List of experiences to be returned

sort_by
string or null
Default: "id"
Enum: "id" "goal_tracking_status" "name" "times_used" "type" "key" "status"

A value to sort audiences by specific field

Defaults to id if not provided

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

include
Array of strings (GoalOptionalFields)
Items Enum: "triggering_rule" "stats"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

only
Array of integers or null <= 200 items

Only retrieve goals with the given ids. Including 'stats' reduces the maximum number of 'only' items to 50.

except
Array of integers <= 200 items

Except goals with the given ids. Including 'stats' reduces the maximum number of 'except' items to 50.

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "status": [
    ],
  • "is_default": true,
  • "search": "string",
  • "tracking": "tracked",
  • "usage": "used",
  • "goal_type": [
    ],
  • "experiences": [
    ],
  • "sort_by": "id",
  • "page": 1,
  • "include": [
    ],
  • "only": [
    ],
  • "except": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific goal

Retrieves detailed information about a single conversion goal, identified by its goal_id. This includes its name, type (e.g., 'visits_page', 'revenue', 'clicks_link'), configuration settings (like URL for page visit goals, or CSS selector for click goals), and triggering rules. The include parameter can fetch additional data like usage statistics.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

goal_id
required
integer

ID of the goal to be retrieved

query Parameters
include
Array of strings (GoalOptionalFields)
Items Enum: "triggering_rule" "stats"

Specifies the list of optional fields which would be included in the response.

Otherwise, the fields that can be passed through this parameter would not be included in the response.

Read more in the section related to Optional Fields

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "name": "string",
  • "key": "string",
  • "description": "string",
  • "is_system": true,
  • "stats": {
    },
  • "triggering_rule": {
    },
  • "selected_default": true,
  • "status": "active",
  • "type": "advanced"
}

Get goal details by its unique key

Retrieves detailed information about a single conversion goal, identified by its user-defined goal_key. Useful if you have a human-readable key for a goal. Otherwise, similar to getting a goal by ID.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

goal_key
required
string

Key of the goal to be retrieved

query Parameters
include
Array of strings (GoalOptionalFields)
Items Enum: "triggering_rule" "stats"

Specifies the list of optional fields which would be included in the response.

Otherwise, the fields that can be passed through this parameter would not be included in the response.

Read more in the section related to Optional Fields

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "name": "string",
  • "key": "string",
  • "description": "string",
  • "is_system": true,
  • "stats": {
    },
  • "triggering_rule": {
    },
  • "selected_default": true,
  • "status": "active",
  • "type": "advanced"
}

Create a new conversion goal

Defines a new conversion goal within a project. Requires specifying the goal name and type (e.g., 'visits_page', 'revenue', 'clicks_link', 'submits_form', 'code_trigger'). Depending on the type, additional settings are needed, such as the target URL for a page visit goal, or the CSS selector for a click goal. The Knowledge Base article "Goals" (Use a goal template section) lists various types.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the goal is to be stored

Request Body schema: application/json

Goal request object to create goal data.

Any of
name
required
string <= 100 characters

A user-defined, friendly name for the goal (e.g., "Completed Purchase", "Newsletter Signup", "Viewed Pricing Page"). This name appears in reports and when selecting goals for experiences.

key
string <= 32 characters

A unique, machine-readable string key for this goal within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference. Example: "completed_purchase_main_flow".

description
string <= 500 characters

An optional, more detailed explanation of what this goal measures or its significance to business objectives.

required
object or null

Defines the logical structure for combining multiple rule conditions. It uses a nested OR -> AND -> OR_WHEN structure.

  • The top-level OR array means if any of its contained AND blocks evaluate to true, the entire rule set is true.
  • Each object within the OR array has an AND array. For this AND block to be true, all of its contained OR_WHEN blocks must evaluate to true.
  • Each object within the AND array has an OR_WHEN array. For this OR_WHEN block to be true, any of its individual RuleElement conditions must evaluate to true. This structure allows for complex logical expressions like (CondA AND CondB) OR (CondC AND CondD).
selected_default
boolean

If true, this goal will be automatically pre-selected when creating new experiences within the project. Useful for commonly tracked primary conversions.

status
string (GoalStatuses)
Enum: "active" "archived"

The current status of a goal:

  • active: The goal is active and will track conversions for experiences it's attached to.
  • archived: The goal is archived and will not track new conversions. Its historical data remains accessible in reports for experiences that previously used it. Archived goals can often be cloned or unarchived. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."
type
required
any

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "key": "string",
  • "description": "string",
  • "triggering_rule": {
    },
  • "selected_default": true,
  • "status": "active",
  • "type": "dom_interaction",
  • "settings": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "name": "string",
  • "key": "string",
  • "description": "string",
  • "is_system": true,
  • "stats": {
    },
  • "triggering_rule": {
    },
  • "selected_default": true,
  • "status": "active",
  • "type": "advanced"
}

Update an existing conversion goal

Modifies the configuration of an existing conversion goal. This can include changing its name, type, status (active/archived), or specific settings like the target URL or triggering rules.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

goal_id
required
integer

ID of the goal to be updated

Request Body schema: application/json

Contains the fields of the goal to be updated. This can include name, description, status, type, settings (specific to goal type), or triggering_rule.

Any of
name
string <= 100 characters

A user-defined, friendly name for the goal (e.g., "Completed Purchase", "Newsletter Signup", "Viewed Pricing Page"). This name appears in reports and when selecting goals for experiences.

key
string <= 32 characters

A unique, machine-readable string key for this goal within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference. Example: "completed_purchase_main_flow".

description
string <= 500 characters

An optional, more detailed explanation of what this goal measures or its significance to business objectives.

object or null

Defines the logical structure for combining multiple rule conditions. It uses a nested OR -> AND -> OR_WHEN structure.

  • The top-level OR array means if any of its contained AND blocks evaluate to true, the entire rule set is true.
  • Each object within the OR array has an AND array. For this AND block to be true, all of its contained OR_WHEN blocks must evaluate to true.
  • Each object within the AND array has an OR_WHEN array. For this OR_WHEN block to be true, any of its individual RuleElement conditions must evaluate to true. This structure allows for complex logical expressions like (CondA AND CondB) OR (CondC AND CondD).
selected_default
boolean

If true, this goal will be automatically pre-selected when creating new experiences within the project. Useful for commonly tracked primary conversions.

status
string (GoalStatuses)
Enum: "active" "archived"

The current status of a goal:

  • active: The goal is active and will track conversions for experiences it's attached to.
  • archived: The goal is archived and will not track new conversions. Its historical data remains accessible in reports for experiences that previously used it. Archived goals can often be cloned or unarchived. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."
type
any

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "key": "string",
  • "description": "string",
  • "triggering_rule": {
    },
  • "selected_default": true,
  • "status": "active",
  • "type": "dom_interaction",
  • "settings": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "name": "string",
  • "key": "string",
  • "description": "string",
  • "is_system": true,
  • "stats": {
    },
  • "triggering_rule": {
    },
  • "selected_default": true,
  • "status": "active",
  • "type": "advanced"
}

Delete a conversion goal

Permanently removes a conversion goal from a project. This action is irreversible. If the goal is in use by active experiences, consider archiving it instead.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

goal_id
required
integer

ID of the goal to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Update multiple goals at once

Allows for changing the status (e.g., active, archived) of multiple goals within a project simultaneously. Requires a list of goal IDs and the target status.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json

Contains a list of goal ids and the target status (e.g., 'active', 'archived') to apply to all of them.

id
required
Array of integers (BulkGoalsIds) [ 1 .. 100 ] items

The list of goals id to delete

status
required
string (GoalStatuses)
Enum: "active" "archived"

The current status of a goal:

  • active: The goal is active and will track conversions for experiences it's attached to.
  • archived: The goal is archived and will not track new conversions. Its historical data remains accessible in reports for experiences that previously used it. Archived goals can often be cloned or unarchived. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."

Responses

Request samples

Content type
application/json
{
  • "id": [
    ],
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Delete multiple goals at once

Permanently removes multiple goals from a project in a single operation. Requires a list of goal IDs. This action is irreversible.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
id
required
Array of integers (BulkGoalsIds) [ 1 .. 100 ] items

The list of goals id to delete

Responses

Request samples

Content type
application/json
{
  • "id": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Clone an existing conversion goal

Creates a new goal as an identical copy of an existing one (specified by goal_id). Useful for creating a similar goal with minor modifications or for templating.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

goal_id
required
integer

ID of the goal to be deleted

query Parameters
include
Array of strings (GoalOptionalFields)
Items Enum: "triggering_rule" "stats"

Specifies the list of optional fields which would be included in the response.

Otherwise, the fields that can be passed through this parameter would not be included in the response.

Read more in the section related to Optional Fields

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "name": "string",
  • "key": "string",
  • "description": "string",
  • "is_system": true,
  • "stats": {
    },
  • "triggering_rule": {
    },
  • "selected_default": true,
  • "status": "active",
  • "type": "advanced"
}

Hypotheses

A hypothesis is an assumption that a proposed change in your website would lead to visitors taking the action that you want them to. Read more information about Hypotheses.

List hypotheses within a project

Retrieves a list of all hypotheses defined for a specific project. A hypothesis is an assumption about a proposed change and its expected impact, forming the basis for an experiment. Supports filtering by status, score, name, and pagination. The Knowledge Base article "Hypotheses (Compass)" explains: "A hypothesis is an assumption that a proposed change in your website would lead to visitors taking the action that you want them to."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
sort_by
string or null
Default: "id"
Enum: "id" "name" "score" "start_date" "status"

A value to sort hypotheses by specific field(s)

Defaults to id if not provided

scoreMax
integer or null
Default: 5
Enum: 0 1 2 3 4 5

The maximum score for hypotheses which you would like to retrieve

scoreMin
integer or null
Default: 0
Enum: 0 1 2 3 4 5

The minimum score for hypotheses which you would like to retrieve

search
string or null <= 200 characters

A search string that would be used to search against hypotheses's name or description

status
Array of strings or null (HypothesisStatuses)
Enum: "applied" "archived" "completed" "draft" "proven" "disproven"

The status of the hypotheses you'd like to be returned; one of the below can be provided

experiences
Array of integers or null

The list of experience ID's used to filter the list of returned hypotheses

tags
Array of integers or null

The list of tag ID's used to filter the list of returned hypotheses

only
Array of integers or null <= 100 items

Only retrieve hypotheses with the given ids.

except
Array of integers <= 100 items

Except hypotheses with the given ids.

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

expand
Array of strings (HypothesesListExpandFields)
Items Enum: "project" "tags"

Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to Expanding Fields

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "sort_by": "id",
  • "scoreMax": 0,
  • "scoreMin": 0,
  • "search": "string",
  • "status": [
    ],
  • "experiences": [
    ],
  • "tags": [
    ],
  • "only": [
    ],
  • "except": [
    ],
  • "page": 1,
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific hypothesis

Retrieves detailed information about a single hypothesis, identified by its hypothesis_id. This includes its name, objective, prioritization score (PIE or ICE), status, associated experiences, and tags.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the hypothesis is stored

hypothesis_id
required
integer

ID of the hypothesis to be retrieve

query Parameters
expand
Array of strings (HypothesisExpandFields)
Items Enum: "project" "tags" "experiences"

Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "name": "string",
  • "url": "string",
  • "project": 0,
  • "prioritization_score": "string",
  • "objective": "string",
  • "status": "applied",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "summary": "string",
  • "description": "string",
  • "created_at": 0,
  • "created_by": "string",
  • "prioritization_score_type": "PIE",
  • "prioritization_score_attributes": {
    },
  • "experiences": [
    ],
  • "tags": [
    ]
}

Create a new hypothesis

Defines a new hypothesis within a project. Requires a name, objective (problem and proposed solution), prioritization model (PIE or ICE) and its scores, status, and optionally, start/end dates, summary, associated experiences, and tags. The Knowledge Base article "Hypotheses (Compass)" details the PIE (Potential, Importance, Ease) and ICE (Impact, Confidence, Ease) models.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the hypothesis is to be stored

query Parameters
expand
Array of strings (HypothesisExpandFields)
Items Enum: "project" "tags" "experiences"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
name
required
string <= 100 characters

A user-defined, concise name for the hypothesis (e.g., "Changing CTA Button Color to Green", "Simplifying Signup Form"). This name appears in the Compass section of Convert.

url
string or null <= 2048 characters

(Optional) A URL relevant to this hypothesis, such as the page where the proposed change would be implemented or a link to supporting research/data.

objective
string <= 5000 characters

A detailed description of the hypothesis. This should clearly state:

  1. The problem observed (e.g., "Low click-through rate on the main CTA").
  2. The proposed solution/change (e.g., "Change the CTA button text from 'Learn More' to 'Get Started Now'").
  3. The expected outcome/impact (e.g., "This will increase clicks on the CTA by 15% because 'Get Started Now' is more action-oriented"). KB: "Hypotheses (Compass)" - "What is a Hypothesis".
status
required
string (HypothesisStatuses)
Enum: "applied" "archived" "completed" "draft" "proven" "disproven"

The current stage or outcome of a hypothesis in its lifecycle:

  • draft: The hypothesis is still being formulated or refined; not yet ready for testing.
  • completed: The hypothesis definition is finalized and it's ready to be linked to an experiment or tested.
  • applied: The hypothesis is currently being tested in one or more active experiences.
  • proven: Testing has concluded, and the hypothesis was validated (i.e., the proposed change led to a positive, statistically significant outcome). Can be moved to Knowledge Base.
  • disproven: Testing has concluded, and the hypothesis was invalidated (i.e., the proposed change did not lead to the expected positive outcome or had a negative impact). Can be moved to Knowledge Base.
  • archived: The hypothesis is no longer active or relevant for current testing but is kept for historical records. KB: "Hypotheses (Compass)" - "Status of Hypothesis".
start_date
string or null <date> <= 10 characters

(Optional) The date (YYYY-MM-DD) when this hypothesis was conceptualized or formally logged.

end_date
string or null <date> <= 10 characters

(Optional) The target date (YYYY-MM-DD) by which this hypothesis is expected to be tested or resolved.

summary
string <= 500 characters

(Optional) A brief summary or key takeaway from this hypothesis, often filled in after testing.

description
string or null <= 5000 characters

This is more details that want to be added besides the name of the hypothesis

Array of objects or null (UploadedFileData)

Files attached to the hypothesis

created_at
integer

Unix timestamp (UTC) indicating when this hypothesis was created in the system.

prioritization_score_type
required
string

A given description of prioritizing model

required
object (PIE_Attributes)

Scores for the PIE (Potential, Importance, Ease) prioritization model. Each attribute is scored on a scale of 1 to 5. KB: "Hypotheses (Compass)" - "PIE prioritization model".

experiences
Array of integers (HypothesisCreateUpdateExperiences) <= 100 items

A list of experience IDs that are testing or were derived from this hypothesis. This links the hypothesis to actual experiments.

Array of integers or TagToCreate (object) or null (TagExpandableRequest)

The list of tags connected to this hypothesis

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "url": "string",
  • "objective": "string",
  • "status": "applied",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "summary": "string",
  • "description": "string",
  • "files": [
    ],
  • "created_at": 0,
  • "prioritization_score_type": "PIE",
  • "prioritization_score_attributes": {
    },
  • "experiences": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "name": "string",
  • "url": "string",
  • "project": 0,
  • "prioritization_score": "string",
  • "objective": "string",
  • "status": "applied",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "summary": "string",
  • "description": "string",
  • "created_at": 0,
  • "created_by": "string",
  • "prioritization_score_type": "PIE",
  • "prioritization_score_attributes": {
    },
  • "experiences": [
    ],
  • "tags": [
    ]
}

Update an existing hypothesis

Modifies the details of an existing hypothesis, such as its name, objective, prioritization scores, status, or associated experiences and tags.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the hypothesis is to be updated

hypothesis_id
required
integer

ID of the hypothesis to be updated

query Parameters
expand
Array of strings (HypothesisExpandFields)
Items Enum: "project" "tags" "experiences"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
name
string <= 100 characters

A user-defined, concise name for the hypothesis (e.g., "Changing CTA Button Color to Green", "Simplifying Signup Form"). This name appears in the Compass section of Convert.

url
string or null <= 2048 characters

(Optional) A URL relevant to this hypothesis, such as the page where the proposed change would be implemented or a link to supporting research/data.

objective
string <= 5000 characters

A detailed description of the hypothesis. This should clearly state:

  1. The problem observed (e.g., "Low click-through rate on the main CTA").
  2. The proposed solution/change (e.g., "Change the CTA button text from 'Learn More' to 'Get Started Now'").
  3. The expected outcome/impact (e.g., "This will increase clicks on the CTA by 15% because 'Get Started Now' is more action-oriented"). KB: "Hypotheses (Compass)" - "What is a Hypothesis".
status
string (HypothesisStatuses)
Enum: "applied" "archived" "completed" "draft" "proven" "disproven"

The current stage or outcome of a hypothesis in its lifecycle:

  • draft: The hypothesis is still being formulated or refined; not yet ready for testing.
  • completed: The hypothesis definition is finalized and it's ready to be linked to an experiment or tested.
  • applied: The hypothesis is currently being tested in one or more active experiences.
  • proven: Testing has concluded, and the hypothesis was validated (i.e., the proposed change led to a positive, statistically significant outcome). Can be moved to Knowledge Base.
  • disproven: Testing has concluded, and the hypothesis was invalidated (i.e., the proposed change did not lead to the expected positive outcome or had a negative impact). Can be moved to Knowledge Base.
  • archived: The hypothesis is no longer active or relevant for current testing but is kept for historical records. KB: "Hypotheses (Compass)" - "Status of Hypothesis".
start_date
string or null <date> <= 10 characters

(Optional) The date (YYYY-MM-DD) when this hypothesis was conceptualized or formally logged.

end_date
string or null <date> <= 10 characters

(Optional) The target date (YYYY-MM-DD) by which this hypothesis is expected to be tested or resolved.

summary
string <= 500 characters

(Optional) A brief summary or key takeaway from this hypothesis, often filled in after testing.

description
string or null <= 5000 characters

This is more details that want to be added besides the name of the hypothesis

Array of objects or null (UploadedFileData)

Files attached to the hypothesis

created_at
integer

Unix timestamp (UTC) indicating when this hypothesis was created in the system.

prioritization_score_type
string

A given description of prioritizing model

object (PIE_Attributes)

Scores for the PIE (Potential, Importance, Ease) prioritization model. Each attribute is scored on a scale of 1 to 5. KB: "Hypotheses (Compass)" - "PIE prioritization model".

experiences
Array of integers (HypothesisCreateUpdateExperiences) <= 100 items

A list of experience IDs that are testing or were derived from this hypothesis. This links the hypothesis to actual experiments.

Array of integers or TagToCreate (object) or null (TagExpandableRequest)

The list of tags connected to this hypothesis

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "url": "string",
  • "objective": "string",
  • "status": "applied",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "summary": "string",
  • "description": "string",
  • "files": [
    ],
  • "created_at": 0,
  • "prioritization_score_type": "PIE",
  • "prioritization_score_attributes": {
    },
  • "experiences": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "name": "string",
  • "url": "string",
  • "project": 0,
  • "prioritization_score": "string",
  • "objective": "string",
  • "status": "applied",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "summary": "string",
  • "description": "string",
  • "created_at": 0,
  • "created_by": "string",
  • "prioritization_score_type": "PIE",
  • "prioritization_score_attributes": {
    },
  • "experiences": [
    ],
  • "tags": [
    ]
}

Update the status of a hypothesis

Changes the status of an existing hypothesis (e.g., from 'draft' to 'completed', 'applied', 'proven', 'disproven', or 'archived'). This helps track the lifecycle of a hypothesis from idea to tested outcome.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the hypothesis is stored

hypothesis_id
required
integer

ID of the hypothesis to be updated

query Parameters
expand
Array of strings (HypothesisExpandFields)
Items Enum: "project" "tags" "experiences"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
status
string (HypothesisStatuses)
Enum: "applied" "archived" "completed" "draft" "proven" "disproven"

The current stage or outcome of a hypothesis in its lifecycle:

  • draft: The hypothesis is still being formulated or refined; not yet ready for testing.
  • completed: The hypothesis definition is finalized and it's ready to be linked to an experiment or tested.
  • applied: The hypothesis is currently being tested in one or more active experiences.
  • proven: Testing has concluded, and the hypothesis was validated (i.e., the proposed change led to a positive, statistically significant outcome). Can be moved to Knowledge Base.
  • disproven: Testing has concluded, and the hypothesis was invalidated (i.e., the proposed change did not lead to the expected positive outcome or had a negative impact). Can be moved to Knowledge Base.
  • archived: The hypothesis is no longer active or relevant for current testing but is kept for historical records. KB: "Hypotheses (Compass)" - "Status of Hypothesis".

Responses

Request samples

Content type
application/json
{
  • "status": "applied"
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "name": "string",
  • "url": "string",
  • "project": 0,
  • "prioritization_score": "string",
  • "objective": "string",
  • "status": "applied",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "summary": "string",
  • "description": "string",
  • "created_at": 0,
  • "created_by": "string",
  • "prioritization_score_type": "PIE",
  • "prioritization_score_attributes": {
    },
  • "experiences": [
    ],
  • "tags": [
    ]
}

Convert a proven/disproven hypothesis to a Knowledge Base entry

Moves a hypothesis (typically one that is 'proven' or 'disproven' after testing) into the Knowledge Base. This archives the learnings from the hypothesis for future reference and organizational learning. The Knowledge Base article "Hypotheses (Compass)" mentions: "Proven hypotheses can then be moved to the Knowledge Base".

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the hypothesis is going to be converted

hypothesis_id
required
integer

ID of the hypothesis to be converted

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "project": 0,
  • "status": "active",
  • "summary": "string",
  • "url": "string",
  • "objective": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "prioritization_score_type": "string",
  • "prioritization_score_attributes": { },
  • "experiences": [
    ],
  • "description": "string",
  • "created_by": "string",
  • "updated_at": 0,
  • "tags": [
    ]
}

Delete a hypothesis

Permanently removes a hypothesis from a project. This action is irreversible.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project from which the hypothesis is to be deleted

hypothesis_id
required
integer

ID of the hypothesis to be deleted

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "name": "string",
  • "url": "string",
  • "project": 0,
  • "prioritization_score": "string",
  • "objective": "string",
  • "status": "applied",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "summary": "string",
  • "description": "string",
  • "created_at": 0,
  • "created_by": "string",
  • "prioritization_score_type": "PIE",
  • "prioritization_score_attributes": {
    },
  • "experiences": [
    ],
  • "tags": [
    ]
}

Update multiple hypotheses at once

Allows for changing the status of multiple hypotheses within a project simultaneously. Requires a list of hypothesis IDs and the target status.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json

Contains a list of hypothesis ids and the target status to apply to all of them.

id
required
Array of integers (BulkHypothesisIds) [ 1 .. 100 ] items

A list of hypothesis unique numerical identifiers to be affected by a bulk operation.

status
required
string (HypothesisStatuses)
Enum: "applied" "archived" "completed" "draft" "proven" "disproven"

The current stage or outcome of a hypothesis in its lifecycle:

  • draft: The hypothesis is still being formulated or refined; not yet ready for testing.
  • completed: The hypothesis definition is finalized and it's ready to be linked to an experiment or tested.
  • applied: The hypothesis is currently being tested in one or more active experiences.
  • proven: Testing has concluded, and the hypothesis was validated (i.e., the proposed change led to a positive, statistically significant outcome). Can be moved to Knowledge Base.
  • disproven: Testing has concluded, and the hypothesis was invalidated (i.e., the proposed change did not lead to the expected positive outcome or had a negative impact). Can be moved to Knowledge Base.
  • archived: The hypothesis is no longer active or relevant for current testing but is kept for historical records. KB: "Hypotheses (Compass)" - "Status of Hypothesis".

Responses

Request samples

Content type
application/json
{
  • "id": [
    ],
  • "status": "applied"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Delete multiple hypotheses at once

Permanently removes multiple hypotheses from a project in a single operation. Requires a list of hypothesis IDs. This action is irreversible.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
id
required
Array of integers (BulkHypothesisIds) [ 1 .. 100 ] items

A list of hypothesis unique numerical identifiers to be affected by a bulk operation.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Knowledge Bases

List Knowledge Base entries within a project

Retrieves a list of all Knowledge Base entries for a specific project. The Knowledge Base stores proven or disproven hypotheses and their outcomes, serving as a repository of experimental learnings. Supports filtering by status, name, and pagination. The Knowledge Base article "Observations Feature Guide" explains: "Knowledge Base - Convert proven hypotheses to serve as a historical record and knowledge resource."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
sort_by
string or null
Default: "name"
Enum: "name" "updated_at" "status"

A value to sort knowledge bases by specific field(s)

Defaults to name if not provided

search
string or null <= 200 characters

A search string that would be used to search against knowledge bases name

status
Array of strings or null (KnowledgeBaseStatuses)
Enum: "active" "archived"

The status of the knowledge bases you'd like to be returned; one of the below can be provided

tags
Array of integers or null

The list of tag ID's used to filter the list of returned knowledge bases

only
Array of integers or null <= 100 items

Only retrieve knowledge bases with the given ids.

except
Array of integers <= 100 items

Except knowledge bases with the given ids.

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

expand
Array of strings (KnowledgeBasesExpandFields)
Items Enum: "project" "tags"

Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to Expanding Fields

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "sort_by": "name",
  • "search": "string",
  • "status": [
    ],
  • "tags": [
    ],
  • "only": [
    ],
  • "except": [
    ],
  • "page": 1,
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific Knowledge Base entry

Retrieves detailed information about a single Knowledge Base entry, identified by its knowledge_base_id. This includes the original hypothesis name, summary of findings, status, and associated tags.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the knowledge base is stored

knowledge_base_id
required
integer

ID of the knowledge base to be retrieve

query Parameters
expand
Array of strings (KnowledgeBasesExpandFields)
Items Enum: "project" "tags"

Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "project": 0,
  • "status": "active",
  • "summary": "string",
  • "url": "string",
  • "objective": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "prioritization_score_type": "string",
  • "prioritization_score_attributes": { },
  • "experiences": [
    ],
  • "description": "string",
  • "created_by": "string",
  • "updated_at": 0,
  • "tags": [
    ]
}

Create a new Knowledge Base entry

Adds a new entry to the Knowledge Base. This is typically done by converting a 'proven' or 'disproven' hypothesis, but can also be used to manually add other experimental learnings. Requires a name, summary, and status.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the knowledge base is to be stored

query Parameters
expand
Array of strings (KnowledgeBasesExpandFields)
Items Enum: "project" "tags"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
name
required
string <= 100 characters

A concise title for the Knowledge Base entry, often derived from the original hypothesis name or a summary of the key learning (e.g., "Green CTA Button Increased Signups by 10%", "Simplified Navigation Did Not Improve Task Completion").

status
string (KnowledgeBaseStatuses)
Default: "active"
Enum: "active" "archived"

The status of a Knowledge Base entry:

  • active: The entry is current and relevant.
  • archived: The entry is kept for historical purposes but may no longer be considered current best practice or has been superseded by newer learnings.
summary
string <= 500 characters

A detailed summary of the findings, insights, and conclusions derived from the tested hypothesis that led to this Knowledge Base entry. This should articulate what was learned, whether the hypothesis was proven or disproven, and any actionable takeaways.

url
string or null <= 2048 characters

Url reference for the knowledge base

objective
string <= 5000 characters

A given description for the knowledge base to easily identify it later

start_date
string or null <date> <= 10 characters

The date in format YYYY-MM-DD

end_date
string or null <date> <= 10 characters

The date in format YYYY-MM-DD

prioritization_score_type
string or null

A given description of prioritizing model

prioritization_score_attributes
object or null

Prioritization score attributes

Array of ExperienceId (integer) or BaseSimpleExperience (object) or null (BaseExperienceExpandable)

The list of experiences connected to this knowledge base

description
string <= 5000 characters

Detailed description of the knowledge base

Array of objects or null (UploadedFileData)

Files attached to the knowledge base

Array of integers or TagToCreate (object) or null (TagExpandableRequest)

The list of tags connected to this observation

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "status": "active",
  • "summary": "string",
  • "url": "string",
  • "objective": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "prioritization_score_type": "string",
  • "prioritization_score_attributes": { },
  • "experiences": [
    ],
  • "description": "string",
  • "files": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "project": 0,
  • "status": "active",
  • "summary": "string",
  • "url": "string",
  • "objective": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "prioritization_score_type": "string",
  • "prioritization_score_attributes": { },
  • "experiences": [
    ],
  • "description": "string",
  • "created_by": "string",
  • "updated_at": 0,
  • "tags": [
    ]
}

Update the status of a Knowledge Base entry

Changes the status of an existing Knowledge Base entry (e.g., from 'active' to 'archived').

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the knowledge base is to be updated

knowledge_base_id
required
integer

ID of the knowledge base to be updated

query Parameters
expand
Array of strings (KnowledgeBasesExpandFields)
Items Enum: "project" "tags"

Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
status
string (KnowledgeBaseStatuses)
Default: "active"
Enum: "active" "archived"

The status of a Knowledge Base entry:

  • active: The entry is current and relevant.
  • archived: The entry is kept for historical purposes but may no longer be considered current best practice or has been superseded by newer learnings.

Responses

Request samples

Content type
application/json
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "project": 0,
  • "status": "active",
  • "summary": "string",
  • "url": "string",
  • "objective": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "prioritization_score_type": "string",
  • "prioritization_score_attributes": { },
  • "experiences": [
    ],
  • "description": "string",
  • "created_by": "string",
  • "updated_at": 0,
  • "tags": [
    ]
}

Delete a Knowledge Base entry

Permanently removes a Knowledge Base entry from a project. This action is irreversible.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project from which the knowledge base is to be deleted

knowledge_base_id
required
integer

ID of the knowledge base to be deleted

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "project": 0,
  • "status": "active",
  • "summary": "string",
  • "url": "string",
  • "objective": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "prioritization_score_type": "string",
  • "prioritization_score_attributes": { },
  • "experiences": [
    ],
  • "description": "string",
  • "created_by": "string",
  • "updated_at": 0,
  • "tags": [
    ]
}

Update multiple Knowledge Base entries at once

Allows for changing the status (e.g., active, archived) of multiple Knowledge Base entries within a project simultaneously. Requires a list of Knowledge Base entry IDs and the target status.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json

Contains a list of Knowledge Base entry ids and the target status to apply to all of them.

id
required
Array of integers (BulkKnowledgeBaseIds) [ 1 .. 100 ] items

A list of Knowledge Base entry unique numerical identifiers to be affected by a bulk operation.

status
required
string (KnowledgeBaseStatuses)
Default: "active"
Enum: "active" "archived"

The status of a Knowledge Base entry:

  • active: The entry is current and relevant.
  • archived: The entry is kept for historical purposes but may no longer be considered current best practice or has been superseded by newer learnings.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ],
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Delete multiple Knowledge Base entries at once

Permanently removes multiple Knowledge Base entries from a project in a single operation. Requires a list of Knowledge Base entry IDs. This action is irreversible.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
id
required
Array of integers (BulkKnowledgeBaseIds) [ 1 .. 100 ] items

A list of Knowledge Base entry unique numerical identifiers to be affected by a bulk operation.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Observations

List observations within a project

Retrieves a list of all observations recorded for a specific project. Observations are initial insights, ideas, or user behaviors noted by the team, which can later be developed into hypotheses. Supports filtering by status, name, tags, and pagination. The Knowledge Base article "Observations Feature Guide" explains: "Observations - Document initial insights directly."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
sort_by
string or null
Default: "name"
Enum: "name" "created_by" "date_added" "status"

A value to sort observations by specific field(s)

Defaults to name if not provided

search
string or null <= 200 characters

A search string that would be used to search against observation's name or description

status
Array of strings or null (ObservationStatuses)
Enum: "active" "archived"

The status of the observations you'd like to be returned; one of the below can be provided

tags
Array of integers or null

The list of tag ID's used to filter the list of returned observations

only
Array of integers or null <= 100 items

Only retrieve observations with the given ids.

except
Array of integers <= 100 items

Except observations with the given ids.

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

expand
Array of strings (ObservationsExpandFields)
Items Enum: "project" "tags"

Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned. Read more in the section related to Expanding Fields

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "sort_by": "name",
  • "search": "string",
  • "status": [
    ],
  • "tags": [
    ],
  • "only": [
    ],
  • "except": [
    ],
  • "page": 1,
  • "expand": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [],
  • "extra": {
    }
}

Get details for a specific observation

Retrieves detailed information about a single observation, identified by its observation_id. This includes its name, description, reference URL, status, associated tags, and any attachments (images/files).

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the observation is stored

observation_id
required
integer

ID of the observation to be retrieve

query Parameters
expand
Array of strings (ObservationsExpandFields)
Items Enum: "project" "tags"

Specifies the list of fields which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Responses

Response samples

Content type
application/json
{}

Create a new observation

Records a new observation within a project. Requires a name, and can include a description, reference URL, status, tags, and attachments (images/files). Observations are the first step in the ideation process, leading to hypotheses. The Knowledge Base article "Observations Feature Guide" details this: "Observations serve as the starting point in documenting insights."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the observation is to be stored

query Parameters
expand
Array of strings (ObservationsExpandFields)
Items Enum: "project" "tags"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
name
required
string <= 100 characters

A user-defined, concise title for the observation (e.g., "Users drop off on pricing page", "High bounce rate on mobile landing page", "Positive feedback on new feature idea").

description
string <= 5000 characters

(Optional) A detailed description of the observation, including context, data points, user quotes, or any relevant details that support the insight.

status
string (ObservationStatuses)
Default: "active"
Enum: "active" "archived"

The current status of an observation in its lifecycle:

  • active: The observation is current, under consideration, or being actively discussed. This is the default for new observations.
  • archived: The observation has been reviewed and is no longer actively being pursued (e.g., deemed not actionable, superseded, or already addressed). It's kept for historical records. Knowledge Base: "Observations Feature Guide" - "Status Management".
url
string <= 2048 characters

(Optional) A URL relevant to this observation, such as the page where the behavior was observed or a link to an analytics report.

Array of objects or null (ObservationImage) <= 3 items

This is the document that is used as a visual representation of the observe feature

Array of objects or null (ObservationFile) <= 3 items

This is the document that is used as a visual representation of the observe feature

Array of integers or TagToCreate (object) or null (TagExpandableRequest)

The list of tags connected to this observation

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "status": "active",
  • "url": "string",
  • "images": [
    ],
  • "files": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{}

Update an existing observation

Modifies the details of an existing observation, such as its name, description, URL, status, tags, or attachments.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the observation is to be updated

observation_id
required
integer

ID of the observation to be updated

query Parameters
expand
Array of strings (ObservationsExpandFields)
Items Enum: "project" "tags"

Specifies the list of objects which would be expanded in the response. Otherwise, only their id would be returned.

Read more in the section related to Expanding Fields

Request Body schema: application/json
name
string <= 100 characters

A user-defined, concise title for the observation (e.g., "Users drop off on pricing page", "High bounce rate on mobile landing page", "Positive feedback on new feature idea").

description
string <= 5000 characters

(Optional) A detailed description of the observation, including context, data points, user quotes, or any relevant details that support the insight.

status
string (ObservationStatuses)
Default: "active"
Enum: "active" "archived"

The current status of an observation in its lifecycle:

  • active: The observation is current, under consideration, or being actively discussed. This is the default for new observations.
  • archived: The observation has been reviewed and is no longer actively being pursued (e.g., deemed not actionable, superseded, or already addressed). It's kept for historical records. Knowledge Base: "Observations Feature Guide" - "Status Management".
url
string <= 2048 characters

(Optional) A URL relevant to this observation, such as the page where the behavior was observed or a link to an analytics report.

Array of objects or null (ObservationImage) <= 3 items

This is the document that is used as a visual representation of the observe feature

Array of objects or null (ObservationFile) <= 3 items

This is the document that is used as a visual representation of the observe feature

Array of integers or TagToCreate (object) or null (TagExpandableRequest)

The list of tags connected to this observation

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "status": "active",
  • "url": "string",
  • "images": [
    ],
  • "files": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{}

Delete an observation

Permanently removes an observation from a project. This action is irreversible.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project from which the observation is to be deleted

observation_id
required
integer

ID of the observation to be deleted

Responses

Response samples

Content type
application/json
{}

Update multiple observations at once

Allows for changing the status (e.g., active, archived) of multiple observations within a project simultaneously. Requires a list of observation IDs and the target status.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json

Contains a list of observation ids and the target status (e.g., 'active', 'archived') to apply to all of them.

id
required
Array of integers (BulkObservationIds) [ 1 .. 100 ] items

A list of observation unique numerical identifiers to be affected by a bulk operation.

status
required
string (ObservationStatuses)
Default: "active"
Enum: "active" "archived"

The current status of an observation in its lifecycle:

  • active: The observation is current, under consideration, or being actively discussed. This is the default for new observations.
  • archived: The observation has been reviewed and is no longer actively being pursued (e.g., deemed not actionable, superseded, or already addressed). It's kept for historical records. Knowledge Base: "Observations Feature Guide" - "Status Management".

Responses

Request samples

Content type
application/json
{
  • "id": [
    ],
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Delete multiple observations at once

Permanently removes multiple observations from a project in a single operation. Requires a list of observation IDs. This action is irreversible.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
id
required
Array of integers (BulkObservationIds) [ 1 .. 100 ] items

A list of observation unique numerical identifiers to be affected by a bulk operation.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Locations

Locations let you target your experiences in the ways that are important to your business.

List locations within a project

Retrieves a list of all locations defined for a specific project. Locations define where on a website an experience will run, based on URL patterns, page tags, or JavaScript conditions. Supports filtering by status, name, and pagination. The Knowledge Base article "Locations" explains: "Locations conditions include the pages on which the experiment will run."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
status
Array of strings or null (LocationStatuses)
Enum: "active" "archived"

List of Location statuses to be returned

is_default
boolean or null

It indicates wherever retrieved locations are default or not

If not provided, it will return all locations. If not provided, it will return all locations

search
string or null <= 200 characters

a search string that would be used to search against Location's name or description

sort_by
string or null
Default: "id"
Enum: "id" "name" "usage" "status" "key"

A value to sort Location by specific field

Defaults to id if not provided

usage
string or null
Enum: "used" "not_used"

It indicates wherever retrieved locations are used or not inside experiences

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

include
Array of strings (LocationIncludeFields)
Items Enum: "rules" "trigger" "stats.experiences_usage"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

only
Array of integers or null <= 100 items

Only retrieve location with the given ids.

except
Array of integers <= 100 items

Except locations with the given ids.

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "status": [
    ],
  • "is_default": true,
  • "search": "string",
  • "sort_by": "id",
  • "usage": "used",
  • "page": 1,
  • "include": [
    ],
  • "only": [
    ],
  • "except": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific location

Retrieves detailed information about a single location, identified by its location_id. This includes its name, status, triggering rules (e.g., URL matches, JS conditions), and the type of trigger (e.g., upon_run, manual, dom_element). The include parameter can fetch additional data like usage statistics.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the Location is stored

location_id
required
integer

ID of the Location to be retrieved

query Parameters
include
Array of strings (LocationIncludeFields)
Items Enum: "rules" "trigger" "stats.experiences_usage"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

Read more in the section related to Optional Fields

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "preset": true,
  • "selected_default": true,
  • "stats": {
    },
  • "rules": {
    },
  • "trigger": {
    }
}

Create a new location

Defines a new location within a project. Requires a name and a set of rules (e.g., URL contains 'product/', JS condition window.userType === 'premium'). Also requires specifying the trigger type (e.g., 'upon_run' to activate when rules match on page load, or 'manual' to activate via JavaScript call). The Knowledge Base article "Creating Effective Experiences: A Guide to Location Setup" describes different trigger options.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the location is to be stored

Request Body schema: application/json
description
string <= 500 characters

An optional, more detailed explanation of this location's purpose or the pages/conditions it targets.

status
string (LocationStatuses)
Default: "active"
Enum: "active" "archived"

The current status of a location:

  • active: The location is active and can be used for targeting experiences.
  • archived: The location is archived and no longer available for new experiences, but its definition is preserved. Archived locations can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."
name
required
string <= 100 characters

A user-defined, friendly name for the location (e.g., "All Product Pages", "Homepage Only", "Checkout Funnel"). This name appears in the Convert UI when selecting locations for experiences.

selected_default
boolean

If true, this location will be automatically pre-selected when creating new experiences within the project. Useful for commonly targeted site areas.

required
object or null

Defines the logical structure for combining multiple rule conditions for a Location. It uses a nested OR -> AND -> OR_WHEN structure, similar to Audience rules, but LocationRuleElement types are restricted to page content/URL attributes.

any (LocationTrigger)

Defines how and when an experience associated with this location should be activated for a visitor who matches the location's rules. The type determines the activation mechanism. Knowledge Base: "Locations" - "Dynamic Website Triggers".

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "selected_default": true,
  • "rules": {
    },
  • "trigger": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "preset": true,
  • "selected_default": true,
  • "stats": {
    },
  • "rules": {
    },
  • "trigger": {
    }
}

Update an existing location

Modifies the configuration of an existing location. This can include changing its name, status (active/archived), triggering rules, or trigger type.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the location is stored

location_id
required
integer

ID of the location to be updated

Request Body schema: application/json
description
string <= 500 characters

An optional, more detailed explanation of this location's purpose or the pages/conditions it targets.

status
string (LocationStatuses)
Default: "active"
Enum: "active" "archived"

The current status of a location:

  • active: The location is active and can be used for targeting experiences.
  • archived: The location is archived and no longer available for new experiences, but its definition is preserved. Archived locations can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."
name
string <= 100 characters

A user-defined, friendly name for the location (e.g., "All Product Pages", "Homepage Only", "Checkout Funnel"). This name appears in the Convert UI when selecting locations for experiences.

selected_default
boolean

If true, this location will be automatically pre-selected when creating new experiences within the project. Useful for commonly targeted site areas.

object or null

Defines the logical structure for combining multiple rule conditions for a Location. It uses a nested OR -> AND -> OR_WHEN structure, similar to Audience rules, but LocationRuleElement types are restricted to page content/URL attributes.

any (LocationTrigger)

Defines how and when an experience associated with this location should be activated for a visitor who matches the location's rules. The type determines the activation mechanism. Knowledge Base: "Locations" - "Dynamic Website Triggers".

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "selected_default": true,
  • "rules": {
    },
  • "trigger": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "preset": true,
  • "selected_default": true,
  • "stats": {
    },
  • "rules": {
    },
  • "trigger": {
    }
}

Delete a location

Permanently removes a location from a project. This action is irreversible. If the location is in use by active experiences, consider archiving it instead or unlinking it from experiences first.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

location_id
required
integer

ID of the location to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Update multiple locations at once

Allows for changing the status (e.g., active, archived) of multiple locations within a project simultaneously. Requires a list of location IDs and the target status.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json

Contains a list of location ids and the target status (e.g., 'active', 'archived') to apply to all of them.

id
required
Array of integers (BulkLocationsIds) [ 1 .. 100 ] items

A list of location unique numerical identifiers to be affected by a bulk operation.

status
required
string (LocationStatuses)
Default: "active"
Enum: "active" "archived"

The current status of a location:

  • active: The location is active and can be used for targeting experiences.
  • archived: The location is archived and no longer available for new experiences, but its definition is preserved. Archived locations can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."

Responses

Request samples

Content type
application/json
{
  • "id": [
    ],
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Delete multiple locations at once

Permanently removes multiple locations from a project in a single operation. Requires a list of location IDs. This action is irreversible.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
id
required
Array of integers (BulkLocationsIds) [ 1 .. 100 ] items

A list of location unique numerical identifiers to be affected by a bulk operation.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

List predefined location templates (presets)

Retrieves a list of predefined location templates (presets) available for use. These presets offer common targeting configurations (e.g., "All Pages", "Homepage") to speed up location setup. The Knowledge Base article "Creating Effective Experiences: A Guide to Location Setup" mentions "Saved Locations" which are user-created, these are system presets.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Clone an existing location

Creates a new location as an identical copy of an existing one (specified by location_id). Useful for creating a similar location with minor modifications or for templating.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

location_id
required
integer

ID of the location to be deleted

query Parameters
include
Array of strings (LocationIncludeFields)
Items Enum: "rules" "trigger" "stats.experiences_usage"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

Read more in the section related to Optional Fields

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "preset": true,
  • "selected_default": true,
  • "stats": {
    },
  • "rules": {
    },
  • "trigger": {
    }
}

Audiences

Audiences let you segment your users in the ways that are important to your business. You can segment by event (e.g., session_start or level_up) and by user property (e.g., Browser/OS, Geo, Language), and combine events, parameters, and properties to include practically any subset of users. Read more information about Audiences.

List audiences within a project

Retrieves a list of all audiences defined for a specific project. Audiences segment visitors based on criteria like behavior, demographics, traffic source, or custom data, to target experiences. Supports filtering by status, type, name, and pagination. The Knowledge Base article "Define Audiences for your Experience" explains: "An 'Audience' is a group of visitors that you want to be included in your experience".

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
status
Array of strings or null (AudienceStatuses)
Enum: "active" "archived"

List of audience statuses to be returned

search
string or null <= 200 characters

a search string that would be used to search against audience's name or description

is_default
boolean or null

A flag to filter audiences by default status

If set to true, only default audiences will be returned, if not set, all audiences will be returned

sort_by
string or null
Default: "id"
Enum: "id" "type" "name" "usage" "status" "key"

A value to sort audiences by specific field

Defaults to id if not provided

type
string or null
Enum: "segmentation" "permanent" "transient"
experiences
Array of integers or null <= 100 items

List of experiences to be returned

usage
string or null
Enum: "used" "not_used"

It indicates wherever retrieved audiences are used or not inside experiences

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

include
Array of strings (AudienceIncludeFields)
Items Enum: "rules" "stats.experiences_usage"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

only
Array of integers or null <= 100 items

Only retrieve audiences with the given ids.

except
Array of integers <= 100 items

Except audiences with the given ids.

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "status": [
    ],
  • "search": "string",
  • "is_default": true,
  • "sort_by": "id",
  • "type": "segmentation",
  • "experiences": [
    ],
  • "usage": "used",
  • "page": 1,
  • "include": [
    ],
  • "only": [
    ],
  • "except": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific audience

Retrieves detailed information about a single audience, identified by its audience_id. This includes its name, type (permanent, transient, segmentation), status, and the rules defining the audience criteria (e.g., browser is Chrome, country is USA, visited specific page). The include parameter can fetch additional data like usage statistics.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the audience is stored

audience_id
required
integer

ID of the audience to be retrieved

query Parameters
include
Array of strings (AudienceIncludeFields)
Items Enum: "rules" "stats.experiences_usage"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

Read more in the section related to Optional Fields

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "preset": true,
  • "selected_default": true,
  • "stats": {
    },
  • "type": "permanent",
  • "rules": {
    }
}

Create a new audience

Defines a new audience within a project. Requires a name, type (permanent, transient, segmentation), and a set of rules defining the audience criteria. Rules can be based on visitor data (browser, device, geo-location, language, visit count, cookie values), traffic sources (UTM parameters, referrer), page tags, or JavaScript conditions. The Knowledge Base article "Define an Advanced Audience" lists many available conditions.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the audience is to be stored

Request Body schema: application/json
description
string <= 500 characters

An optional, more detailed explanation of the audience's purpose or criteria, aiding in identification and management.

status
string (AudienceStatuses)
Enum: "active" "archived"

The status of an audience:

  • active: The audience is currently active and can be used for targeting experiences.
  • archived: The audience is no longer active and cannot be used for new experiences, but its definition and past usage data are preserved. Archived audiences can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."
name
required
string <= 100 characters

A user-defined, friendly name for the audience (e.g., "New Visitors from USA", "Repeat Purchasers - Mobile"). This name appears in the Convert UI when selecting audiences for experiences.

selected_default
boolean

If true, this audience will be automatically pre-selected when creating new experiences within the project. Useful for commonly targeted segments.

type
required
string (AudienceTypesNoUrl)

Defines the behavior and persistence of an audience that does not use URL-based conditions in its rules.

  • permanent: Once a visitor matches the audience criteria, they are permanently considered part of this audience for future sessions and evaluations, even if their characteristics change later. The matching is checked only at the initial bucketing time.
  • transient: A visitor must match the audience criteria upon each evaluation (e.g., on every page load or when an experiment is rechecked) to be included. If conditions are no longer met, the visitor is no longer part of the audience for that specific evaluation. For Full Stack projects, only transient and segmentation (if applicable without URL rules) are valid.
required
object or null

Similar to RuleObject, but the individual RuleElementNoUrl conditions within OR_WHEN arrays cannot include URL-based matching types. Used for 'permanent' or 'transient' audiences where URL context is not persistently evaluated or relevant for the audience type.

Responses

Request samples

Content type
application/json
Example
{
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "selected_default": true,
  • "type": "permanent",
  • "rules": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "preset": true,
  • "selected_default": true,
  • "stats": {
    },
  • "type": "permanent",
  • "rules": {
    }
}

Update an existing audience

Modifies the configuration of an existing audience. This can include changing its name, type, status (active/archived), or the rules defining its criteria.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the audience is stored

audience_id
required
integer

ID of the audience to be updated

Request Body schema: application/json
description
string <= 500 characters

An optional, more detailed explanation of the audience's purpose or criteria, aiding in identification and management.

status
string (AudienceStatuses)
Enum: "active" "archived"

The status of an audience:

  • active: The audience is currently active and can be used for targeting experiences.
  • archived: The audience is no longer active and cannot be used for new experiences, but its definition and past usage data are preserved. Archived audiences can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."
name
string <= 100 characters

A user-defined, friendly name for the audience (e.g., "New Visitors from USA", "Repeat Purchasers - Mobile"). This name appears in the Convert UI when selecting audiences for experiences.

selected_default
boolean

If true, this audience will be automatically pre-selected when creating new experiences within the project. Useful for commonly targeted segments.

type
string (AudienceTypesNoUrl)

Defines the behavior and persistence of an audience that does not use URL-based conditions in its rules.

  • permanent: Once a visitor matches the audience criteria, they are permanently considered part of this audience for future sessions and evaluations, even if their characteristics change later. The matching is checked only at the initial bucketing time.
  • transient: A visitor must match the audience criteria upon each evaluation (e.g., on every page load or when an experiment is rechecked) to be included. If conditions are no longer met, the visitor is no longer part of the audience for that specific evaluation. For Full Stack projects, only transient and segmentation (if applicable without URL rules) are valid.
object or null

Similar to RuleObject, but the individual RuleElementNoUrl conditions within OR_WHEN arrays cannot include URL-based matching types. Used for 'permanent' or 'transient' audiences where URL context is not persistently evaluated or relevant for the audience type.

Responses

Request samples

Content type
application/json
Example
{
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "selected_default": true,
  • "type": "permanent",
  • "rules": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "preset": true,
  • "selected_default": true,
  • "stats": {
    },
  • "type": "permanent",
  • "rules": {
    }
}

Delete an audience

Permanently removes an audience from a project. This action is irreversible. If the audience is in use by active experiences, consider archiving it instead or unlinking it from experiences first.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

audience_id
required
integer

ID of the audience to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Update multiple audiences at once

Allows for changing the status (e.g., active, archived) of multiple audiences within a project simultaneously. Requires a list of audience IDs and the target status.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json

Contains a list of audience ids and the target status (e.g., 'active', 'archived') to apply to all of them.

id
required
Array of integers (BulkAudiencesIds) [ 1 .. 100 ] items

A list of audience unique numerical identifiers to be affected by a bulk operation.

status
required
string (AudienceStatuses)
Enum: "active" "archived"

The status of an audience:

  • active: The audience is currently active and can be used for targeting experiences.
  • archived: The audience is no longer active and cannot be used for new experiences, but its definition and past usage data are preserved. Archived audiences can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."

Responses

Request samples

Content type
application/json
{
  • "id": [
    ],
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Delete multiple audiences at once

Permanently removes multiple audiences from a project in a single operation. Requires a list of audience IDs. This action is irreversible.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
id
required
Array of integers (BulkAudiencesIds) [ 1 .. 100 ] items

A list of audience unique numerical identifiers to be affected by a bulk operation.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

List predefined audience templates (presets)

Retrieves a list of predefined audience templates (presets) available for use. These presets offer common targeting configurations (e.g., "New Visitors", "Mobile Users", "Visitors from Google") to speed up audience setup. The Knowledge Base article "Define an Audience from the Templates" describes this.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Clone an existing audience

Creates a new audience as an identical copy of an existing one (specified by audience_id). Useful for creating a similar audience with minor modifications or for templating.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

audience_id
required
integer

ID of the audience to be deleted

query Parameters
include
Array of strings (AudienceIncludeFields)
Items Enum: "rules" "stats.experiences_usage"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

Read more in the section related to Optional Fields

Responses

Response samples

Content type
application/json
Example
{
  • "id": 0,
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "preset": true,
  • "selected_default": true,
  • "stats": {
    },
  • "type": "permanent",
  • "rules": {
    }
}

Domains

Domains define websites which will be used in experiences in your projects.

List domains associated with a project

Retrieves a list of all website domains configured for a specific project. The Convert tracking script will operate on these domains to run experiences and track visitors. Wildcard domains (e.g., *.example.com) are supported. As per the Knowledge Base: "Active Websites: The domains you would like to use inside the project. Make sure you always add new domains here..."

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json

Optional filters for listing domains within a project, primarily pagination parameters (page, results_per_page).

onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

only
Array of integers or null <= 100 items

Only retrieve domains with the given ids.

except
Array of integers <= 100 items

Except domains with the given ids.

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "page": 1,
  • "only": [
    ],
  • "except": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific domain in a project

Retrieves information about a single domain associated with a project, identified by its domain_id. This includes the domain URL and whether the Convert tracking code was detected on it.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the domain is stored

domain_id
required
integer

ID of the domain to be retrieved

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "string",
  • "code_installed": false
}

Get domain details by its URL

Retrieves information about a domain by matching its URL (exact or wildcard) instead of its ID. Useful if you know the domain URL but not its internal Convert ID.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the domain is stored

Request Body schema: application/json

Contains the url (which can be an exact match or include wildcards like *.example.com) to search for among the project's associated domains.

url
string <= 255 characters

URL by which to search the domain. The match can be an exact one or an wildcard one.

Responses

Request samples

Content type
application/json
{
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "string",
  • "code_installed": false
}

Verify Convert tracking code installation on a domain

Checks if the Convert tracking script for the specified project is correctly installed and detectable on the given URL (which must belong to the domain identified by domain_id). Updates the code_installed status of the domain object. The Knowledge Base article "Tracking Script Installation Verification" describes this UI feature.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the domain is stored

domain_id
required
integer

ID of the domain to which the given URL belongs. An error would be returned if the URL is not under this domain.

Request Body schema: application/json

Contains the specific url (which must fall under the path-parameter domain_id) on which to check for the presence and correct installation of the Convert tracking script.

url
string <= 255 characters

URL on which to check the tracking code installed. The given URL needs to be under the domain passes as parameter or otherwise an error would be returned.

Responses

Request samples

Content type
application/json
{
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "string",
  • "code_installed": false
}

Add a new domain to a project

Associates a new website domain (e.g., https://www.example.com) with the specified project. The Convert tracking script for this project should then be installed on this domain to enable experiments. Wildcards like https://*.example.com can be used to include all subdomains.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the domain is to be stored

Request Body schema: application/json
url
required
string <= 150 characters ^(http|https)://

Domain's homepage url

code_installed
boolean
Default: false

Indicating whether code installed check passed sometimes in the past.

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "code_installed": false
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "string",
  • "code_installed": false
}

Update an existing domain in a project

Modifies the URL of an existing domain associated with a project.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the domain is to be stored

domain_id
required
integer

ID of the domain to be updated

Request Body schema: application/json
url
string <= 150 characters ^(http|https)://

Domain's homepage url

code_installed
boolean
Default: false

Indicating whether code installed check passed sometimes in the past.

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "code_installed": false
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "url": "string",
  • "code_installed": false
}

Remove a domain from a project

De-associates a domain from the specified project. After deletion, Convert experiences will no longer run on this domain for this project.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the domain is to be stored

domain_id
required
integer

ID of the domain to be delete

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Remove multiple domains from a project

De-associates multiple domains from the specified project in a single operation. Requires a list of domain IDs to be removed.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
id
required
Array of integers (BulkDomainsIds) [ 1 .. 100 ] items

The list of domains id to delete

Responses

Request samples

Content type
application/json
{
  • "id": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Cdn Images

Various endpoints that allow Image Assets loaded through Convert's CDN to be managed

List uploaded images for a project

Retrieves a list of images that have been uploaded to the Convert CDN for a specific project. These images can be used in experience variations. Supports pagination. The Knowledge Base article "Image Upload Guidelines for Convert Visual Editor" mentions image upload limits.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

Request Body schema: application/json

Optional parameters to control pagination for the list of CDN images. Use start_from with an image key (filename) to list images after that specific one, and max_results to limit the number of images returned per request.

start_from
string

The key (filename on CDN) of an image from which to start listing. The returned list will include images lexicographically after this key. Used for pagination.

max_results
integer or null [ 0 .. 100 ]
Default: 50

The maximum number of images to return in this request. Used for pagination. Default is 50.

Responses

Request samples

Content type
application/json
{
  • "start_from": "string",
  • "max_results": 50
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Upload an image to the project's CDN storage

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

Request Body schema: multipart/form-data
image_name
required
string <= 200 characters

The desired filename (including extension, e.g., "new_banner.png", "logo_variant.svg") for the image as it will be stored on the CDN.

image
required
string <binary>

The binary image file content to be uploaded. Constraints: Max 2MB; JPEG, PNG, GIF, WEBP, SVG.

Responses

Response samples

Content type
application/json
{
  • "cdn_url": "string",
  • "key": "string"
}

Delete an image from the project's CDN storage

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

image_key
required
string

The key of the image file to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Files

Various endpoints that allow File Assets loaded through Convert's to be managed

Upload a generic file to project storage

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

Request Body schema: multipart/form-data
file_name
required
string <= 200 characters

The desired name for the file as it will be stored and identified in Convert (e.g., "campaign_brief.pdf", "logo_variation.svg"). Include the file extension.

file
required
string <binary>

The actual binary file content to be uploaded. Constraints:

  • Maximum file size: 5MB.
  • Supported types: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV, JPG, JPEG, BMP, GIF, PNG, WEBP, SVG.

Responses

Response samples

Content type
application/json
{}

Get content of an uploaded file

Retrieves the content of a previously uploaded file, identified by its file_key. The file content is returned base64 encoded.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

file_key
required
string

The key of the file to retrieve

Responses

Response samples

Content type
application/json
{}

Delete an uploaded file from project storage

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

file_key
required
string

The key of the file to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Tags

Tags define tag labels for your project.

List tags within a project

Retrieves a list of all tags defined for a specific project. Tags are keywords used to categorize and organize experiences, goals, audiences, etc., for easier management and filtering. The Knowledge Base article "Adding tags to your Experiences" explains their use.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json

Optional filters for listing tags, primarily search for tag names and pagination parameters (page, results_per_page). Also supports only/except for specific tag IDs.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

only
Array of integers or null <= 100 items

Only retrieve tags with the given ids.

except
Array of integers <= 100 items

Except tags with the given ids.

search
string or null <= 100 characters

A search string that would be used to search against Tag's name

Responses

Request samples

Content type
application/json
{
  • "results_per_page": 30,
  • "page": 1,
  • "only": [
    ],
  • "except": [
    ],
  • "search": "string"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific tag

Retrieves information about a single tag, identified by its tag_id. This includes its name and description.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the tag is stored

tag_id
required
integer

ID of the tag to be retrieve

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string"
}

Create a new tag

Defines a new tag within a project. Requires a tag name and an optional description. Tags can then be applied to experiences, goals, etc., to help organize them.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the tag is to be stored

Request Body schema: application/json
name
required
string <= 100 characters

The user-defined name of the tag (e.g., "Q3 Campaigns", "Homepage Tests", "High Priority", "Mobile Specific"). This is the primary identifier shown in the UI.

description
string <= 200 characters

(Optional) A brief explanation of the tag's purpose or the criteria for its application.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string"
}

Update an existing tag

Modifies the name or description of an existing tag.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the tag is to be stored

tag_id
required
integer

ID of the tag to be updated

Request Body schema: application/json
name
string <= 100 characters

The user-defined name of the tag (e.g., "Q3 Campaigns", "Homepage Tests", "High Priority", "Mobile Specific"). This is the primary identifier shown in the UI.

description
string <= 200 characters

(Optional) A brief explanation of the tag's purpose or the criteria for its application.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string"
}

Delete a tag

Permanently removes a tag from a project. This does not delete the items (experiences, goals, etc.) that were associated with the tag, but simply removes the tag association.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project from which the tag is to be deleted

tag_id
required
integer

ID of the tag to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Delete multiple tags at once

Permanently removes multiple tags from a project in a single operation. Requires a list of tag IDs.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
id
required
Array of integers (BulkTagsIds) [ 1 .. 100 ] items

A list of tag unique numerical identifiers to be affected by a bulk delete operation.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Features

Features can be created only under Fullstack Projects

List features within a Full Stack project

Retrieves a list of all features defined for a specific Full Stack project. Features are used for feature flagging and server-side experimentation, allowing control over functionality and variables. Supports filtering by name, key, status, and pagination. The Knowledge Base article "Full Stack Experiments on Convert" provides context.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction
string or null
Default: "desc"
Enum: "asc" "desc"

The direction for sorting the list results, based on the sort_by field.

  • asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
  • desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.
search
string or null <= 100 characters

A search string that would be used to search against Feature's id, name, key and description

only
Array of integers or null <= 100 items

Only retrieve features with the given ids.

except
Array of integers <= 100 items

Except features with the given ids.

sort_by
string or null
Enum: "id" "name" "key" "status"

A value to sort features by specific field

Defaults to id if not provided

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

include
Array of strings (FeatureOptionalFields)
Items Value: "stats"

Specifies the list of fields to be included in the response, which otherwise would not be sent.

Responses

Request samples

Content type
application/json
{
  • "onlyCount": true,
  • "results_per_page": 30,
  • "sort_direction": "asc",
  • "search": "string",
  • "only": [
    ],
  • "except": [
    ],
  • "sort_by": "id",
  • "page": 1,
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Get details for a specific feature

Retrieves detailed information about a single feature within a Full Stack project, identified by its feature_id. This includes its name, key, status, description, and defined variables (with their types and default values).

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

feature_id
required
integer

ID of the feature to be retrieved

query Parameters
include
Array of strings (FeatureOptionalFields)
Items Value: "stats"

Specifies the list of optional fields which would be included in the response.

Otherwise, the fields that can be passed through this parameter would not be included in the response.

Read more in the section related to Optional Fields

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "active",
  • "key": "string",
  • "stats": {
    },
  • "description": "string",
  • "variables": [
    ]
}

Get feature details by its unique key

Retrieves detailed information about a single feature, identified by its user-defined feature_key. Useful if you have a human-readable key for a feature. Otherwise, similar to getting a feature by ID.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

feature_key
required
string

Key of the feature to be retrieved

query Parameters
include
Array of strings (FeatureOptionalFields)
Items Value: "stats"

Specifies the list of optional fields which would be included in the response.

Otherwise, the fields that can be passed through this parameter would not be included in the response.

Read more in the section related to Optional Fields

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "active",
  • "key": "string",
  • "stats": {
    },
  • "description": "string",
  • "variables": [
    ]
}

Create a new feature for a Full Stack project

Defines a new feature within a Full Stack project. Requires a name, a unique key, and a list of variables associated with the feature. Each variable has a key, type (string, boolean, integer, float, json), and a default value. Features are used in Full Stack experiments to control different code paths or configurations.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project into which the feature is to be stored

Request Body schema: application/json
name
required
string <= 100 characters

A user-defined, friendly name for the feature (e.g., "New Checkout Process", "Beta User Dashboard"). This name appears in the Convert UI.

status
string (FeatureStatuses)
Default: "active"
Enum: "active" "archived"

The current status of a feature:

  • active: The feature is active and can be used in Full Stack experiments. Its variables can be controlled by experiences.
  • archived: The feature is archived and no longer available for new experiments. Existing experiments using it might behave based on last known configuration or default values.
key
string <= 32 characters

A unique, machine-readable string key for this feature (e.g., "new_checkout_flow", "beta_dashboard_enabled"). This key is used by the SDKs to identify and retrieve the feature's configuration and variable values. It's typically auto-generated from the name if not specified, but can be user-defined.

description
string <= 200 characters

An optional, more detailed explanation of the feature's purpose, what it controls, or its intended use cases.

required
Array of any (FeatureVariable)

An array of FeatureVariable objects that define the configurable parameters associated with this feature. For example, a feature "Button Customization" might have variables like "buttonColor" (string), "buttonText" (string), and "isEnabled" (boolean). The values of these variables can be different for each variation of an experience that uses this feature.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "status": "active",
  • "key": "string",
  • "description": "string",
  • "variables": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "active",
  • "key": "string",
  • "stats": {
    },
  • "description": "string",
  • "variables": [
    ]
}

Update an existing feature

Modifies the configuration of an existing feature in a Full Stack project. This can include changing its name, description, status (active/archived), or its associated variables (adding, removing, or modifying variables and their default values).

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

feature_id
required
integer

ID of the feature to be updated

Request Body schema: application/json
name
string <= 100 characters

A user-defined, friendly name for the feature (e.g., "New Checkout Process", "Beta User Dashboard"). This name appears in the Convert UI.

status
string (FeatureStatuses)
Default: "active"
Enum: "active" "archived"

The current status of a feature:

  • active: The feature is active and can be used in Full Stack experiments. Its variables can be controlled by experiences.
  • archived: The feature is archived and no longer available for new experiments. Existing experiments using it might behave based on last known configuration or default values.
key
string <= 32 characters

A unique, machine-readable string key for this feature (e.g., "new_checkout_flow", "beta_dashboard_enabled"). This key is used by the SDKs to identify and retrieve the feature's configuration and variable values. It's typically auto-generated from the name if not specified, but can be user-defined.

description
string <= 200 characters

An optional, more detailed explanation of the feature's purpose, what it controls, or its intended use cases.

Array of any (FeatureVariable)

An array of FeatureVariable objects that define the configurable parameters associated with this feature. For example, a feature "Button Customization" might have variables like "buttonColor" (string), "buttonText" (string), and "isEnabled" (boolean). The values of these variables can be different for each variation of an experience that uses this feature.

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "active",
  • "key": "string",
  • "description": "string",
  • "variables": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "active",
  • "key": "string",
  • "stats": {
    },
  • "description": "string",
  • "variables": [
    ]
}

Delete a feature

Permanently removes a feature from a Full Stack project. This action is irreversible. If the feature is in use by active experiments, consider its impact before deletion.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

feature_id
required
integer

ID of the feature to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Update multiple features at once

Allows for changing the status (e.g., active, archived) of multiple features within a Full Stack project simultaneously. Requires a list of feature IDs and the target status.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json

Contains a list of feature ids and the target status (e.g., 'active', 'archived') to apply to all of them.

id
required
Array of integers (BulkFeaturesIds) [ 1 .. 100 ] items

A list of feature unique numerical identifiers to be affected by a bulk operation.

status
required
string (FeatureStatuses)
Default: "active"
Enum: "active" "archived"

The current status of a feature:

  • active: The feature is active and can be used in Full Stack experiments. Its variables can be controlled by experiences.
  • archived: The feature is archived and no longer available for new experiments. Existing experiments using it might behave based on last known configuration or default values.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ],
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Delete multiple features at once

Permanently removes multiple features from a Full Stack project in a single operation. Requires a list of feature IDs. This action is irreversible.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to which save/retrieved data is connected

Request Body schema: application/json
id
required
Array of integers (BulkFeaturesIds) [ 1 .. 100 ] items

A list of feature unique numerical identifiers to be affected by a bulk operation.

Responses

Request samples

Content type
application/json
{
  • "id": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "errors": [
    ]
}

Visitor Insights

Visitor Insights for the project

List Convert Signals™ (visitor frustration sessions)

Retrieves a list of Convert Signals™ sessions for a project. Convert Signals™ "is a special anonymous and privacy oriented session recording feature...It shows only really clear frustrations, errors and usability signals of real users". Use this to identify sessions where visitors experienced issues like rage clicks, dead clicks, or scroll stalls. Supports filtering by date, experience, variation, location, country, device, browser, and more.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

Request Body schema: application/json
start_time
number or null

Unix timestamp (seconds since epoch, UTC) marking the beginning of the time range. If null, implies from the beginning of data.

end_time
number or null

Unix timestamp (seconds since epoch, UTC) marking the end of the time range. If null, implies up to the current time.

utc_offset
integer (UTC_Offset) [ -43200 .. 50400 ]
Default: 0

The time offset from Coordinated Universal Time (UTC) in seconds. For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200. Used for interpreting or displaying date/time information according to a specific timezone.

page
integer >= 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

results_per_page
integer or null [ 0 .. 50 ]
Default: 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

onlyCount
boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

object
location_id
integer

The ID of the location to filter by

starred
string
watched
string
object or null
object
object or null
object or null
containsPage
string
notContainsPage
string
object or null

The duration of the signal session in seconds

object or null
entryPage
string
exitPage
string
referrerURLs
Array of strings
trafficChannels
Array of strings
adCampaignLabels
Array of strings
recordingId
string

Responses

Request samples

Content type
application/json
{
  • "start_time": 0,
  • "end_time": 0,
  • "utc_offset": 0,
  • "page": 1,
  • "results_per_page": 30,
  • "onlyCount": true,
  • "experience": {
    },
  • "location_id": 0,
  • "starred": "string",
  • "watched": "string",
  • "country": {
    },
  • "os": {
    },
  • "browser": {
    },
  • "devices": {
    },
  • "containsPage": "string",
  • "notContainsPage": "string",
  • "duration": {
    },
  • "pageCount": {
    },
  • "entryPage": "string",
  • "exitPage": "string",
  • "referrerURLs": [
    ],
  • "trafficChannels": [
    ],
  • "adCampaignLabels": [
    ],
  • "recordingId": "string"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "extra": {
    }
}

Delete a specific Convert Signals™ session

Permanently removes a recorded Convert Signals™ session, identified by its signal_session_id.

path Parameters
account_id
required
integer

ID of the account that owns the retrieved/saved data

project_id
required
integer

ID of the project to be retrieved

signal_session_id
required
string

ID of the signal session to be deleted

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Account

This object represents details of a tenant in Convert SAAS app.

id
integer

The unique numerical identifier for the account.

accountType
string

Defines the type of the account:

  • main: A primary account that can have sub-accounts and manages its own billing.
  • sub: A secondary account existing under a main account, often used by agencies to manage client activities. Sub-accounts share quotas from the parent.
name
string <= 200 characters

The user-defined, friendly name for the account (e.g., "Client X Marketing", "My Company Inc.").

accessRole
string
Enum: "owner" "account_manager" "admin" "browse" "edit" "publish" "review"

The predefined names for user access roles within the Convert system. Each role grants a specific set of permissions.

  • owner: Highest level, full control over account, billing, users, and all projects. Typically the account creator.
  • account_manager: Broad administrative rights over the account, often including billing and user management, but might not be able to delete the account itself.
  • admin: Full control over projects they are assigned to, including creating/editing/deleting experiences, goals, audiences, and managing project settings. May also manage project-level collaborators.
  • browse: Read-only access. Can view experiences, reports, and settings but cannot make changes.
  • edit: Can create and modify entities like experiences, goals, audiences within assigned projects, but typically cannot activate/publish experiences or manage project settings.
  • publish: Can do everything an 'editor' can, plus activate/pause/complete experiences.
  • review: Can view and comment, but not make direct changes. Suited for stakeholders who need to approve or provide feedback. Knowledge Base: "Collaborators - Share With Multiple Users / Accounts" (describes access levels).
access_all_projects
boolean

Indicates if the authenticated user has access to all projects within this account by default, or if access is granted on a per-project basis.

object

Various Account level settings that can be controlled by the user

object

Billing related data and settings

object (BillingPlanLimitsAndCapabilities)
object or null

General usage statistics for the account, typically for the current billing period. This is an optional field in API responses, included via include[]=stats.

Example
{
  • "id": null,
  • "accountType": "main",
  • "name": "string",
  • "accessRole": "owner",
  • "access_all_projects": true,
  • "settings": {
    },
  • "billing": {
    },
  • "limitsAndCapabilities": {
    },
  • "stats": {
    }
}

Access Role

This is the access role that defines the permissions one user has over accounts/projects.

name
string
object (RolePermissions)
{
  • "name": "string",
  • "permissions": {
    }
}

User

This object represents an user that exists in the system and which can do operations over data.

object
object (UserPreferences)

A collection of user-specific settings that customize their experience within the Convert application UI. These preferences do not impact the execution or behavior of live experiments.

isSudo
boolean

(Internal) If true, indicates the user is currently operating in "sudo" (super-administrator impersonation) mode.

mfa_backup_codes
Array of arrays

(Not Implemented / For Future Use) A list of one-time backup codes for Multi-Factor Authentication (MFA). These would be provided when MFA is enabled and can be used if the primary MFA device is unavailable.

{
  • "profileData": {
    },
  • "preferences": {
    },
  • "isSudo": true,
  • "mfa_backup_codes": [ ]
}

Account Access

This defines how a user gets access to accounts(Collaborates into accounts)

first_name
string <= 200 characters

Collaborator's first name

last_name
string <= 200 characters

Collaborator's last name

Array of objects

List of projects the user can access

email
string <= 100 characters

The email address of the collaborator or invitee.

user_id
string or null

The unique system identifier for an active Convert user. Null if the user is only an invitee (pending acceptance).

{
  • "first_name": "string",
  • "last_name": "string",
  • "accesses": [
    ],
  • "email": "string",
  • "user_id": "string"
}

API Key

This object describes an API key which is used to authenticate, same as the owner of the respective project/account

name
string <= 100 characters

A user-defined, friendly name for the API key to help identify its purpose or the application using it (e.g., "Reporting Dashboard Integration", "Nightly Data Sync Script").

auth_type
string (ApiKeyAuthTypes)
Enum: "requestSigning" "secretKey"

The authentication type for this API key:

  • requestSigning: Each request must be signed with the key and a hash sent in the header (most secure)
  • secretKey: A simpler authentication method using the secret key as a Bearer token in the Authorization header (good security)
projects
Array of numbers or null

An optional list of project IDs that this API key is authorized to access. If null or an empty list, the key typically grants access to all projects within the account it belongs to. This allows for granular control over API key permissions.

key_id
string

The public identifier part of the API key pair (ApplicationID). This is sent in the Convert-Application-ID header.

key_secret
string

The secret part of the API key pair (ApplicationSecretKey). This is used to sign API requests and is critical for authentication. Important: The full key_secret is only returned at the time of API key creation. For security reasons, subsequent retrievals of this API key will show this field masked (e.g., with asterisks or partially hidden). Store the secret securely upon creation.

{
  • "name": "string",
  • "auth_type": "requestSigning",
  • "projects": [
    ],
  • "key_id": "string",
  • "key_secret": "string"
}

Project

This object describes a project which holds together a set of Domains, Experiences, Goals, Audiences

global_javascript
string or null

Custom JavaScript code that will be included on all pages where this project's tracking script is installed. This script runs before any experience-specific code, making it suitable for global helper functions, third-party integrations setup (like analytics), or defining global variables. KB: "Project, Experience, Variation Javascript" - "Global Project JavaScript".

name
string <= 200 characters

A user-defined, friendly name for the project (e.g., "Main Website Optimization", "Q3 Marketing Campaigns", "Mobile App Features").

project_type
string
Default: "web"
Enum: "web" "fullstack"

The type of project, determining its capabilities and how it's used:

  • web: For traditional website A/B testing, MVT, Split URL, personalization, and deploys using the client-side JavaScript tracking snippet.
  • fullstack: For server-side experiments, feature flagging, and mobile app testing using Convert's Full Stack SDKs. KB: "Full Stack Experiments on Convert".
object

Project settings used for reporting

object

General operational settings for the project.

object

Project-wide settings for various third-party integrations (e.g., Google Analytics, Crazy Egg, Hotjar). Experience-level settings can sometimes override these.

status
string (ProjectStatuses)
Enum: "active" "inactive" "suspended"

The overall status of a project:

  • active: The project is active, and experiences within it can run and track data.
  • inactive: The project is inactive (archived or paused). No experiences within it will run, and no new data will be tracked.
  • suspended: The project (or account) has been suspended, typically due to billing issues or terms of service violations. Services are disabled.
object or null

Configuration for using a custom domain (CNAME) to serve the Convert tracking script and receive tracking data. This can improve branding and potentially reduce issues with ad blockers or third-party cookie restrictions. Requires DNS setup.

object
Default: {"production":{"label":"Production","is_default":true}}

A user-defined map of environments for this project (e.g., "production", "staging", "development"). Each environment has its own variant of the tracking script. Experiences are typically configured to run in a specific environment. The number of allowed environments depends on the account's subscription plan. KB: "The Environments Feature".

Array of integers or SimpleGoal (object) (SimpleGoalExpandable)

A list of Goal IDs that will be automatically added to any new experience created within this project.

Array of integers or SimpleAudience (object) (SimpleAudienceExpandable)

A list of Audience IDs that will be automatically added to any new experience created within this project.

Array of integers or SimpleLocation (object) (SimpleLocationExpandable)

A list of Location IDs that will be automatically added to any new experience created within this project.

id
integer

Unique identifier representing a specific project in an user account. The project Id is part of the tracking snippet

accessRole
string (AccessRoleNames)
Enum: "owner" "account_manager" "admin" "browse" "edit" "publish" "review"

The predefined names for user access roles within the Convert system. Each role grants a specific set of permissions.

  • owner: Highest level, full control over account, billing, users, and all projects. Typically the account creator.
  • account_manager: Broad administrative rights over the account, often including billing and user management, but might not be able to delete the account itself.
  • admin: Full control over projects they are assigned to, including creating/editing/deleting experiences, goals, audiences, and managing project settings. May also manage project-level collaborators.
  • browse: Read-only access. Can view experiences, reports, and settings but cannot make changes.
  • edit: Can create and modify entities like experiences, goals, audiences within assigned projects, but typically cannot activate/publish experiences or manage project settings.
  • publish: Can do everything an 'editor' can, plus activate/pause/complete experiences.
  • review: Can view and comment, but not make direct changes. Suited for stakeholders who need to approve or provide feedback. Knowledge Base: "Collaborators - Share With Multiple Users / Accounts" (describes access levels).
owner_email
string

Used only internally - An email of project owner. This field will exist only if project type is shared.

account_id
integer

The unique ID of the account under which this project is created. Account ID is also part of the tracking snippet

created_at
integer

Unix timestamp when project was created, in UTC time.

modified_at
integer

Unix timestamp when project was last modified, in UTC time.

tracking_snippet
string

The tracking code that needs to be placed on site in order to serve experiences from this project.

type
string
Enum: "own" "shared"

Used only internally - A value which describes project ownership. Can be own or shared.

object

Various stats for this project. Optional field, controlled using include fields

Array of objects (Domain)

The list of websites included in this project.

sdk_key
string or null

An autogenerated hash key used to retrieve data of fullstack project. Available only for fullstack projects type.

{
  • "global_javascript": "string",
  • "name": "string",
  • "project_type": "web",
  • "reporting_settings": {
    },
  • "settings": {
    },
  • "integrations_settings": {
    },
  • "status": "active",
  • "custom_domain": {
    },
  • "environments": {
    },
  • "default_goals": [
    ],
  • "default_audiences": [
    ],
  • "default_locations": [
    ],
  • "id": 0,
  • "accessRole": "owner",
  • "owner_email": "string",
  • "account_id": 0,
  • "created_at": 0,
  • "modified_at": 0,
  • "tracking_snippet": "string",
  • "type": "own",
  • "stats": {
    },
  • "domains": [
    ],
  • "sdk_key": "string"
}

SDK Key

This object describes an SDK key which is used to get data under respective project/account

name
string <= 100 characters

A user-defined, friendly name for the SDK key to help identify its purpose or the application/service using it (e.g., "Production Backend API", "Staging iOS App").

sdk_key
string

Unique identifier used to authenticate requests to Convert's serving API endpoints. This key is required to fetch experiments, personalizations and other serving data via the API (see /doc/serving). Generated automatically when creating a new SDK key.

sdk_secret
string or null

Secret key used for SDK authentication. This value is only returned in full when the SDK key is first created. In subsequent GET requests, the secret will be partially redacted (e.g., "abc12*****123") for security purposes. When this is null, the SDK key can be used without authentication (public access).

environment
string

The specific environment within the Full Stack project that this SDK key is associated with (e.g., "production", "development", "staging"). The SDK will fetch configurations relevant to this environment. This must match one of the environments defined at the project level. KB: "The Environments Feature".

status
string (SdkKeyStatuses)
Default: "enabled"
Enum: "enabled" "disabled"

Indicates whether the SDK key is active and can be used for API authentication. When disabled, all requests using this key will be rejected.

{
  • "name": "string",
  • "sdk_key": "string",
  • "sdk_secret": "string",
  • "environment": "string",
  • "status": "enabled"
}

Domain

This object describes one domain part of a Project. This only applies for Web type projects

id
integer

Domain ID.

url
string <= 150 characters ^(http|https)://

Domain's homepage url

code_installed
boolean
Default: false

Indicating whether code installed check passed sometimes in the past.

{
  • "id": 0,
  • "url": "string",
  • "code_installed": false
}

Experience

id
integer

Experience's ID which identify an experience in the system

integer or Project (object) (ProjectExpandable)
Array of objects (ExperienceAlert)
Array of objects (ExperienceCollaborator)
Array of integers or Audience (any) (AudienceExpandable)

The list of audiences for which this experience is supposed to run

Array of integers or Location (object) (LocationExpandable)

The list of locations on which this experience is supposed to run

Array of integers or Goal (any) (GoalExpandable)

The list of goals connected to this experience; experience of type deploy does not have goals attached;

Array of integers or Tag (object) (TagExpandable)

The list of tags connected to this experience

Array of objects (MultipageExperiencePage)

Only for multipage experience type

Array of objects (ExperienceUserCustomizations) <= 100 items

A list of user-defined key-value pairs for customizing UI elements or behavior related to this experience within the Convert application itself. These do not affect the live experiment seen by visitors.

object

Experience's condensed statistics(only for experiences that get access to a report)

Array of integers or CollapsedExperienceVariationData (object) or ExperienceVariationBaseExtended (object) (ExperienceVariation)

The list of variations of this experience.

Note: This is the final list of variations so any variation not provided, which was previously connected, would get deleted.

description
string <= 500 characters

An optional, detailed explanation of the experience's purpose, hypothesis, or specific changes being tested.

start_time
integer or null

Unix timestamp (UTC) indicating when the experience was first activated (status changed to 'active'). Null or 0 if the experience has never been started.

end_time
integer or null

Unix timestamp (UTC) indicating when the experience was last stopped (e.g., paused or completed). Null or 0 if the experience is currently active or has never been stopped.

global_js
string

Custom JavaScript code that will be executed for all visitors bucketed into this experience, before any variation-specific code is applied. Useful for setting up common functionalities or variables needed by multiple variations. KB: "Project, Experience, Variation Javascript" - "Global Experience JavaScript".

global_css
string

Custom CSS rules that will be applied for all visitors bucketed into this experience, before any variation-specific CSS. Useful for common styling adjustments needed across all variations.

name
string <= 100 characters

A user-defined, friendly name for the experience (e.g., "Homepage Headline Test", "Checkout Funnel Optimization Q3"). This name is prominent in the Convert UI and reports.

key
string <= 32 characters

A unique, machine-readable key or identifier for this experience within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference (e.g., in Full Stack SDKs or API calls). Example: "homepage_headline_test_q3".

primary_goal
integer

The ID of the main conversion goal this experience is intended to optimize. Performance against this primary goal often determines the "winner" of an A/B test and is highlighted in reports. KB: "Experiment Report" - "Primary Goal".

objective
string or null <= 5000 characters

A detailed statement outlining the objective of this experience. This often includes the hypothesis being tested, the problem it aims to solve, the proposed solution (the variations), and the expected impact on key metrics. Connects to the "Hypotheses (Compass)" feature.

object (ExperienceSettings)

Experience's settings list

object or null

(Deprecated) The legacy way to define on which pages the experience should run, using a set of include/exclude rules based on URL components or page tags. Modern experiences should use the locations array instead for more flexible targeting.

status
string (ExperienceStatuses)
Enum: "draft" "active" "paused" "completed" "scheduled" "archived" "deleted"
traffic_distribution
number decimal places <= 4 [ 0 .. 100 ]

The percentage of total eligible website traffic (matching audience and location criteria) that will be directed into this entire experience. For example, a value of 50 means 50% of eligible visitors will participate, while the other 50% will see the default website content and not be tracked for this experience. The traffic within the experience is then further split among its variations based on variations[].traffic_distribution. KB: "What is an Traffic Distribution?".

type
string (ExperienceTypes)
Enum: "a/b" "a/a" "mvt" "split_url" "multipage" "deploy" "a/b_fullstack" "feature_rollout"

The type of optimization activity:

  • a/b: Standard A/B test comparing an original page/element against one or more variations. Changes made via Visual Editor or code. KB: "What is an Experiment?".
  • a/a: Tests the original page against an identical copy of itself to validate tracking setup and ensure no inherent bias. KB: "A/A Experiments".
  • mvt: Multivariate test, testing combinations of changes across multiple sections of a page. KB: "Creating a Multivariate Experiment".
  • split_url: Redirects traffic between different URLs to test entirely different page versions. KB: "How do Split URL Experiments work?".
  • multipage: Tests a consistent set of changes across a sequence of pages (funnel). KB: "Create Multipage Experiences".
  • deploy: Rolls out a specific set of changes to a targeted audience without A/B comparison reporting. KB: "What about Deployments?".
  • a/b_fullstack: An A/B test conducted using a Full Stack SDK, potentially involving server-side changes. KB: "Full Stack Experiments on Convert".
  • feature_rollout: A Full Stack experience for gradually rolling out a new feature, often using feature flags.
url
string <uri> <= 2048 characters

The primary URL used to load the page in Convert's Visual Editor when creating or editing this experience's variations. For Split URL tests, this is typically the URL of the original (control) page.

version
number

An internal version number for the experience, incremented upon certain modifications.

Array of ExperienceIntegrationBaidu (object) or ExperienceIntegrationClicktale (object) or ExperienceIntegrationClicky (object) or ExperienceIntegrationCnzz (object) or ExperienceIntegrationCrazyegg (object) or ExperienceIntegrationEconda (object) or ExperienceIntegrationEulerian (object) or ExperienceIntegrationGoogleAnalytics (any) or ExperienceIntegrationGosquared (object) or ExperienceIntegrationHeapanalytics (object) or ExperienceIntegrationHotjar (object) or ExperienceIntegrationMixpanel (object) or ExperienceIntegrationMouseflow (object) or ExperienceIntegrationPiwik (object) or ExperienceIntegrationSegmentio (object) or ExperienceIntegrationSitecatalyst (object) or ExperienceIntegrationWoopra (object) or ExperienceIntegrationYsance (object)

A list of configurations for third-party integrations enabled for this experience (e.g., Google Analytics, Hotjar, Mixpanel). Each object specifies the provider and any provider-specific settings (like a GA Custom Dimension index).

Array of objects

Information about the generation status and timestamps of screenshots for each variation in this experience. Used by the UI.

environments
Array of strings
Deprecated

(Deprecated) List of environment names where this experience will run. Use the singular environment field instead.

environment
string

The specific environment (e.g., "production", "staging", "development") within the project where this experience is intended to run. This must match one of the environments defined at the project level. If not set, it typically defaults to the project's default environment (often "production"). KB: "The Environments Feature".

{
  • "id": 0,
  • "project": 0,
  • "alerts": [
    ],
  • "collaborators": [
    ],
  • "audiences": [
    ],
  • "locations": [
    ],
  • "goals": [
    ],
  • "tags": [
    ],
  • "multipage_pages": [
    ],
  • "customizations": [
    ],
  • "stats": {
    },
  • "variations": [
    ],
  • "description": "string",
  • "start_time": 0,
  • "end_time": 0,
  • "global_js": "string",
  • "global_css": "string",
  • "name": "string",
  • "key": "string",
  • "primary_goal": 0,
  • "objective": "string",
  • "settings": {
    },
  • "site_area": {
    },
  • "status": "draft",
  • "traffic_distribution": 100,
  • "type": "a/b",
  • "version": 0,
  • "integrations": [
    ],
  • "screenshots_info": [
    ],
  • "environments": [
    ],
  • "environment": "string"
}

Experience Section

Internally, every experience's variation is made by combining one Section and on Version, as if it would be a Multivariate experiment. In case of a non Multivariate experiment, the experience has only one section and therefore each version under it will correspond to one Variation

id
string [ 1 .. 2 ] characters ^[0-9a-z]{1,2}$

A unique identifier for this section within the MVT experience (e.g., "s1", "01", "ab"). Typically a short string (1-2 characters). This ID helps in structuring the MVT test.

name
string <= 200 characters

A user-defined, friendly name for this section (e.g., "Page Headline", "Main Call-to-Action Button", "Hero Image"). This name appears in MVT setup and reports.

Array of strings or SectionVersion (object)

Version definition.

Each Multivariate experience is made of a list of Sections and a list of Versions

Than, variations of a Multivariate experience are made of all possible combinations of versions, takin one from each section.

Example: Experience has Section A and Section B. Section A has Version 1 and Version 2, Section B has Version 3 and Version 4

The resulting experience's variations will be the following:

  1. Section A - Version 1 + Section B - Version 3
  2. Section A - Version 2 + Section B - Version 3
  3. Section A - Version 1 + Section B - Version 4
  4. Section A - Version 1 + Section B - Version 4
{
  • "id": "st",
  • "name": "string",
  • "versions": [
    ]
}

Section Version

The version is an entity that lives under a section in order to group together the changes that compose the experience. In case of a non Multivariate experience, each version corresponds to one variation. in the case of a MVT experiment, one variation would be made by combining one version from each of the defined sections.

id
string [ 1 .. 2 ] characters ^[0-9a-z]{1,2}$

A unique identifier for this version within its parent section (e.g., "v1", "02", "ab"). Typically a short string (1-2 characters). This ID is used to construct the overall MVT variation combinations.

name
string <= 200 characters

A user-defined, friendly name for this version (e.g., "Red Button", "Headline Option A", "Original Image"). This name appears in MVT setup and reports.

Array of integers or ExperienceChange (any)
Array of integers
{
  • "id": "st",
  • "name": "string",
  • "changes": [
    ],
  • "variations": [
    ]
}

Variation

A variation is the object that reference all the changes presented to a visitor through one experience.

id
integer

Variation unique ID

name
string <= 200 characters

A user-defined, friendly name for the variation (e.g., "Original Homepage", "Variation B - Green Button", "Personalized Offer for New Users"). This name appears in reports and the Convert UI.

description
string or null <= 2000 characters

An optional, more detailed explanation of what this variation entails or what changes it implements compared to the original or other variations.

is_baseline
boolean

If true, this variation is considered the baseline (control) against which other variations in the experience are compared for performance. Typically, the "Original" variation is the baseline. Only one variation per experience can be the baseline. Knowledge Base: "What is a Baseline?"

traffic_distribution
number decimal places <= 4 [ 0 .. 100 ]

The percentage of eligible traffic allocated to this specific variation. The sum of traffic_distribution for all active variations within an experience should ideally be 100% of the traffic allocated to the experience itself. For Multi-Armed Bandit (MAB) experiences, this value may be dynamically adjusted by the system. Knowledge Base: "What is an Traffic Distribution?"

key
string <= 32 characters

A unique, machine-readable key or identifier for this variation within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference (e.g., in Full Stack SDKs). Example: "control", "treatment_A".

status
string (ExperienceVariationStatuses)
Enum: "stopped" "running"
Array of integers or ExperienceChange (any)

An array of changes that this variation would apply.

{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "is_baseline": true,
  • "traffic_distribution": 100,
  • "key": "string",
  • "status": "stopped",
  • "changes": [
    ]
}

Experience Change

This object represents one change that is presented to the visitor through the experience. A change is connected to a a Version which in turn is connected to the Variation which gets presented to the user.

id
integer

The unique numerical identifier for this specific change.

type
string
object

A flexible object containing the specific details and content for this change, structured according to the change type. For example, for customCode, it would contain js and css strings. For defaultRedirect, it would contain original_pattern and variation_pattern. This field is included by default when fetching a single ExperienceChange but might be omitted in list views unless specified in an include parameter.

Example
{
  • "id": 0,
  • "type": "richStructure",
  • "data": {
    }
}

Goal

A goal is the object which defines how a conversion would be tracked.

id
integer

The unique numerical identifier for the goal.

name
string <= 100 characters

A user-defined, friendly name for the goal (e.g., "Completed Purchase", "Newsletter Signup", "Viewed Pricing Page"). This name appears in reports and when selecting goals for experiences.

key
string <= 32 characters

A unique, machine-readable string key for this goal within the project. Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference. Example: "completed_purchase_main_flow".

description
string <= 500 characters

An optional, more detailed explanation of what this goal measures or its significance to business objectives.

is_system
boolean

Indicates if this is a system-defined default goal (e.g., "Decrease Bounce Rate", "Increase Engagement"). System goals cannot be deleted but their usage can be controlled.

object (GoalStats)
object or null

Defines the logical structure for combining multiple rule conditions. It uses a nested OR -> AND -> OR_WHEN structure.

  • The top-level OR array means if any of its contained AND blocks evaluate to true, the entire rule set is true.
  • Each object within the OR array has an AND array. For this AND block to be true, all of its contained OR_WHEN blocks must evaluate to true.
  • Each object within the AND array has an OR_WHEN array. For this OR_WHEN block to be true, any of its individual RuleElement conditions must evaluate to true. This structure allows for complex logical expressions like (CondA AND CondB) OR (CondC AND CondD).
selected_default
boolean

If true, this goal will be automatically pre-selected when creating new experiences within the project. Useful for commonly tracked primary conversions.

status
string (GoalStatuses)
Enum: "active" "archived"

The current status of a goal:

  • active: The goal is active and will track conversions for experiences it's attached to.
  • archived: The goal is archived and will not track new conversions. Its historical data remains accessible in reports for experiences that previously used it. Archived goals can often be cloned or unarchived. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."
type
any
Example
{
  • "id": 0,
  • "name": "string",
  • "key": "string",
  • "description": "string",
  • "is_system": true,
  • "stats": {
    },
  • "triggering_rule": {
    },
  • "selected_default": true,
  • "status": "active",
  • "type": "advanced"
}

Location

This object describes an Location, which can be used to target experiences.

id
integer

The unique numerical identifier for the location.

description
string <= 500 characters

An optional, more detailed explanation of this location's purpose or the pages/conditions it targets.

status
string (LocationStatuses)
Default: "active"
Enum: "active" "archived"

The current status of a location:

  • active: The location is active and can be used for targeting experiences.
  • archived: The location is archived and no longer available for new experiences, but its definition is preserved. Archived locations can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."
name
string <= 100 characters

A user-defined, friendly name for the location (e.g., "All Product Pages", "Homepage Only", "Checkout Funnel"). This name appears in the Convert UI when selecting locations for experiences.

preset
boolean

Indicates if this location is a system-defined preset (e.g., "All Pages"). Preset locations cannot be modified directly but can be used as templates.

selected_default
boolean

If true, this location will be automatically pre-selected when creating new experiences within the project. Useful for commonly targeted site areas.

object

Statistics related to the usage of this location.

object or null

Defines the logical structure for combining multiple rule conditions for a Location. It uses a nested OR -> AND -> OR_WHEN structure, similar to Audience rules, but LocationRuleElement types are restricted to page content/URL attributes.

any (LocationTrigger)

Defines how and when an experience associated with this location should be activated for a visitor who matches the location's rules. The type determines the activation mechanism. Knowledge Base: "Locations" - "Dynamic Website Triggers".

{
  • "id": 0,
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "preset": true,
  • "selected_default": true,
  • "stats": {
    },
  • "rules": {
    },
  • "trigger": {
    }
}

Audience

This object describes an Audience, which can be used to target experiences.

id
integer

The unique numerical identifier for the audience.

description
string <= 500 characters

An optional, more detailed explanation of the audience's purpose or criteria, aiding in identification and management.

status
string (AudienceStatuses)
Enum: "active" "archived"

The status of an audience:

  • active: The audience is currently active and can be used for targeting experiences.
  • archived: The audience is no longer active and cannot be used for new experiences, but its definition and past usage data are preserved. Archived audiences can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."
name
string <= 100 characters

A user-defined, friendly name for the audience (e.g., "New Visitors from USA", "Repeat Purchasers - Mobile"). This name appears in the Convert UI when selecting audiences for experiences.

preset
boolean

Indicates if this audience is a system-defined preset (e.g., "All Visitors", "Mobile Users"). Preset audiences cannot be modified directly but can be used as templates.

selected_default
boolean

If true, this audience will be automatically pre-selected when creating new experiences within the project. Useful for commonly targeted segments.

object

Statistics related to the usage of this audience.

type
string (AudienceTypesNoUrl)

Defines the behavior and persistence of an audience that does not use URL-based conditions in its rules.

  • permanent: Once a visitor matches the audience criteria, they are permanently considered part of this audience for future sessions and evaluations, even if their characteristics change later. The matching is checked only at the initial bucketing time.
  • transient: A visitor must match the audience criteria upon each evaluation (e.g., on every page load or when an experiment is rechecked) to be included. If conditions are no longer met, the visitor is no longer part of the audience for that specific evaluation. For Full Stack projects, only transient and segmentation (if applicable without URL rules) are valid.
object or null

Similar to RuleObject, but the individual RuleElementNoUrl conditions within OR_WHEN arrays cannot include URL-based matching types. Used for 'permanent' or 'transient' audiences where URL context is not persistently evaluated or relevant for the audience type.

Example
{
  • "id": 0,
  • "description": "string",
  • "status": "active",
  • "name": "string",
  • "preset": true,
  • "selected_default": true,
  • "stats": {
    },
  • "type": "permanent",
  • "rules": {
    }
}

Hypothesis

id
integer

The unique numerical identifier for the hypothesis.

name
string <= 100 characters

A user-defined, concise name for the hypothesis (e.g., "Changing CTA Button Color to Green", "Simplifying Signup Form"). This name appears in the Compass section of Convert.

url
string or null <= 2048 characters

(Optional) A URL relevant to this hypothesis, such as the page where the proposed change would be implemented or a link to supporting research/data.

integer or Project (object) (ProjectExpandable)
prioritization_score
string

The calculated priority score for this hypothesis, based on the chosen prioritization_score_type (PIE or ICE) and its attribute scores. Helps in ranking hypotheses to decide which to test next. KB: "Hypotheses (Compass)" - "How to Prioritize a Hypothesis".

objective
string <= 5000 characters

A detailed description of the hypothesis. This should clearly state:

  1. The problem observed (e.g., "Low click-through rate on the main CTA").
  2. The proposed solution/change (e.g., "Change the CTA button text from 'Learn More' to 'Get Started Now'").
  3. The expected outcome/impact (e.g., "This will increase clicks on the CTA by 15% because 'Get Started Now' is more action-oriented"). KB: "Hypotheses (Compass)" - "What is a Hypothesis".
status
string (HypothesisStatuses)
Enum: "applied" "archived" "completed" "draft" "proven" "disproven"

The current stage or outcome of a hypothesis in its lifecycle:

  • draft: The hypothesis is still being formulated or refined; not yet ready for testing.
  • completed: The hypothesis definition is finalized and it's ready to be linked to an experiment or tested.
  • applied: The hypothesis is currently being tested in one or more active experiences.
  • proven: Testing has concluded, and the hypothesis was validated (i.e., the proposed change led to a positive, statistically significant outcome). Can be moved to Knowledge Base.
  • disproven: Testing has concluded, and the hypothesis was invalidated (i.e., the proposed change did not lead to the expected positive outcome or had a negative impact). Can be moved to Knowledge Base.
  • archived: The hypothesis is no longer active or relevant for current testing but is kept for historical records. KB: "Hypotheses (Compass)" - "Status of Hypothesis".
start_date
string or null <date> <= 10 characters

(Optional) The date (YYYY-MM-DD) when this hypothesis was conceptualized or formally logged.

end_date
string or null <date> <= 10 characters

(Optional) The target date (YYYY-MM-DD) by which this hypothesis is expected to be tested or resolved.

summary
string <= 500 characters

(Optional) A brief summary or key takeaway from this hypothesis, often filled in after testing.

description
string or null <= 5000 characters

This is more details that want to be added besides the name of the hypothesis

Array of objects or null (UploadedFileData)

Files attached to the hypothesis

created_at
integer

Unix timestamp (UTC) indicating when this hypothesis was created in the system.

created_by
string or null

The name or identifier of the user who created this hypothesis.

prioritization_score_type
string

A given description of prioritizing model

object (PIE_Attributes)

Scores for the PIE (Potential, Importance, Ease) prioritization model. Each attribute is scored on a scale of 1 to 5. KB: "Hypotheses (Compass)" - "PIE prioritization model".

Array of ExperienceId (integer) or BaseSimpleExperience (object) or null (BaseExperienceExpandable)

The list of experiences connected to this hypothesis

Array of integers or Tag (object) or null (TagExpandable)

The list of tags connected to this hypothesis

Example
{
  • "id": 0,
  • "name": "string",
  • "url": "string",
  • "project": 0,
  • "prioritization_score": "string",
  • "objective": "string",
  • "status": "applied",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "summary": "string",
  • "description": "string",
  • "created_at": 0,
  • "created_by": "string",
  • "prioritization_score_type": "PIE",
  • "prioritization_score_attributes": {
    },
  • "experiences": [
    ],
  • "tags": [
    ]
}

Knowledge Base

id
integer

The unique numerical identifier for this Knowledge Base entry.

name
string <= 100 characters

A concise title for the Knowledge Base entry, often derived from the original hypothesis name or a summary of the key learning (e.g., "Green CTA Button Increased Signups by 10%", "Simplified Navigation Did Not Improve Task Completion").

integer or Project (object) (ProjectExpandable)
status
string (KnowledgeBaseStatuses)
Default: "active"
Enum: "active" "archived"

The status of a Knowledge Base entry:

  • active: The entry is current and relevant.
  • archived: The entry is kept for historical purposes but may no longer be considered current best practice or has been superseded by newer learnings.
summary
string <= 500 characters

A detailed summary of the findings, insights, and conclusions derived from the tested hypothesis that led to this Knowledge Base entry. This should articulate what was learned, whether the hypothesis was proven or disproven, and any actionable takeaways.

url
string or null <= 2048 characters

Url reference for the knowledge base

objective
string <= 5000 characters

A given description for the knowledge base to easily identify it later

start_date
string or null <date> <= 10 characters

The date in format YYYY-MM-DD

end_date
string or null <date> <= 10 characters

The date in format YYYY-MM-DD

prioritization_score_type
string or null

A given description of prioritizing model

prioritization_score_attributes
object or null

Prioritization score attributes

Array of ExperienceId (integer) or BaseSimpleExperience (object) or null (BaseExperienceExpandable)

The list of experiences connected to this knowledge base

description
string <= 5000 characters

Detailed description of the knowledge base

Array of objects or null (UploadedFileData)

Files attached to the knowledge base

created_by
string or null

The name or identifier of the user who created this Knowledge Base entry (often the person who marked the source hypothesis as proven/disproven).

updated_at
integer

Unix timestamp (UTC) indicating when this Knowledge Base entry was last updated or created.

Array of integers or Tag (object) or null (TagExpandable)

The list of tags connected to this knowledge base

{
  • "id": 0,
  • "name": "string",
  • "project": 0,
  • "status": "active",
  • "summary": "string",
  • "url": "string",
  • "objective": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "prioritization_score_type": "string",
  • "prioritization_score_attributes": { },
  • "experiences": [
    ],
  • "description": "string",
  • "created_by": "string",
  • "updated_at": 0,
  • "tags": [
    ]
}

Observation

id
integer

The unique numerical identifier for the observation.

name
string <= 100 characters

A user-defined, concise title for the observation (e.g., "Users drop off on pricing page", "High bounce rate on mobile landing page", "Positive feedback on new feature idea").

description
string <= 5000 characters

(Optional) A detailed description of the observation, including context, data points, user quotes, or any relevant details that support the insight.

integer or Project (object) (ProjectExpandable)
status
string (ObservationStatuses)
Default: "active"
Enum: "active" "archived"

The current status of an observation in its lifecycle:

  • active: The observation is current, under consideration, or being actively discussed. This is the default for new observations.
  • archived: The observation has been reviewed and is no longer actively being pursued (e.g., deemed not actionable, superseded, or already addressed). It's kept for historical records. Knowledge Base: "Observations Feature Guide" - "Status Management".
url
string <= 2048 characters

(Optional) A URL relevant to this observation, such as the page where the behavior was observed or a link to an analytics report.

created_by
string or null

The name or identifier of the user who created this observation.

created_at
integer

Unix timestamp (UTC) indicating when this observation was created in the system.

Array of objects or null (ObservationImageData)
Deprecated

This is the document that is used as a visual representation of the observe feature

Array of objects or null (UploadedFileData)

This is the document that is used as a visual representation of the observe feature

Array of integers or Tag (object) or null (TagExpandable)

The list of tags connected to this observation

{}

Feature

id
integer

The unique numerical identifier for the feature.

name
string <= 100 characters

A user-defined, friendly name for the feature (e.g., "New Checkout Process", "Beta User Dashboard"). This name appears in the Convert UI.

status
string (FeatureStatuses)
Default: "active"
Enum: "active" "archived"

The current status of a feature:

  • active: The feature is active and can be used in Full Stack experiments. Its variables can be controlled by experiences.
  • archived: The feature is archived and no longer available for new experiments. Existing experiments using it might behave based on last known configuration or default values.
key
string <= 32 characters

A unique, machine-readable string key for this feature (e.g., "new_checkout_flow", "beta_dashboard_enabled"). This key is used by the SDKs to identify and retrieve the feature's configuration and variable values. It's typically auto-generated from the name if not specified, but can be user-defined.

object (FeatureStats)
description
string <= 200 characters

An optional, more detailed explanation of the feature's purpose, what it controls, or its intended use cases.

Array of any (FeatureVariable)

An array of FeatureVariable objects that define the configurable parameters associated with this feature. For example, a feature "Button Customization" might have variables like "buttonColor" (string), "buttonText" (string), and "isEnabled" (boolean). The values of these variables can be different for each variation of an experience that uses this feature.

{
  • "id": 0,
  • "name": "string",
  • "status": "active",
  • "key": "string",
  • "stats": {
    },
  • "description": "string",
  • "variables": [
    ]
}

Tag

id
integer

The unique numerical identifier for the tag.

name
string <= 100 characters

The user-defined name of the tag (e.g., "Q3 Campaigns", "Homepage Tests", "High Priority", "Mobile Specific"). This is the primary identifier shown in the UI.

description
string <= 200 characters

(Optional) A brief explanation of the tag's purpose or the criteria for its application.

{
  • "id": 0,
  • "name": "string",
  • "description": "string"
}

Cdn Image

cdn_url
string

The publicly accessible URL of the image on the Content Delivery Network (CDN). This URL can be used directly in <img> tags or CSS.

key
string

The unique key or path identifier for this image within Convert's CDN storage for the project (e.g., "project_images/my_hero_image.jpg"). This key is used for managing the image (e.g., deletion) and can be used for pagination (start_from).

{
  • "cdn_url": "string",
  • "key": "string"
}

File

url
string

The direct URL from which this file can be accessed or downloaded. This URL points to Convert's file storage.

key
string

The unique storage key (often including the filename and a unique prefix/suffix) for this file within Convert's system. This key is used to retrieve or delete the file.

file_name
string

The original filename of the uploaded file, as provided by the user during upload (e.g., "annual_report.pdf", "user_avatar.png").

file_size
integer

The size of the file in bytes.

mime_type
string

The MIME type of the file (e.g., "application/pdf", "image/jpeg", "text/csv"), indicating its format.

status
string
Enum: "success" "error"

Indicates the status of the file, primarily relevant during or immediately after an upload operation.

message
string

A message related to the file's status, providing more details in case of an error during upload.

{}