API Reference
API Reference

Experiments List

List the existing experiments

GET/api/v1/experiments/

Authentication

Syllable-API-Keyrequired

Send Syllable-API-Key in the header.

Need a credential? Create or manage an API token in the Syllable Console.

Parameters

Query parameters

page integer | null query optional

The page number from which to start (0-based)

Default 0Minimum 0Example 0
limit integer query optional

The maximum number of items to return

Default 25Minimum 0Example 25
search_fields enum<string>[] query optional

String names of fields to search. Correspond by index to search field values

Default []Example name
Item schema
itemsenum<string>required
Allowed values ["id","name","name_exact","description","status","target_id","agent_id","created_at","updated_at","started_at","stopped_at"]
search_field_values string[] query optional

Values of fields to search. Correspond by index to search fields. Unless field name contains "list", an individual search field value cannot be a list

Default []Example Some Object Name
Item schema
itemsstringrequired
order_by enum<string> | null query optional

The field whose value should be used to order the results

Allowed values ["id","name","name_exact","description","status","target_id","agent_id","created_at","updated_at","started_at","stopped_at"]Example name
order_by_direction enum<string> | null query optional

The direction in which to order the results

Allowed values ["asc","desc"]
fields enum<string>[] | null query optional

The fields to include in the response

Default []Example []
Item schema
itemsenum<string>required
Allowed values ["id","name","name_exact","description","status","target_id","agent_id","created_at","updated_at","started_at","stopped_at"]
start_datetime string | null query optional

The start datetime for filtering results

Example 2023-01-01T00:00:00Z
end_datetime string | null query optional

The end datetime for filtering results

Example 2024-01-01T00:00:00Z

Responses

200Successful Response

application/json

response ListResponse_ExperimentResponse_ required
5 fields
itemsExperimentResponse[]required

List of items returned from the query

Item schema
itemsExperimentResponserequired

Response model for experiment operations.

An experiment splits the traffic of one channel target between two or more agents, so that the agents can be compared on the same population. One variant is the control the others are measured against. Each variant is a weighted pointer to the agent that variant runs; the weights are relative and not percentages.

12 fields
idintegerrequired

The internal ID of the experiment

namestringrequired

The name of the experiment

target_idinteger | nullrequired

The channel target being split, or null if that target has since been deleted. A running experiment always has one.

variantsDaoExperimentVariantDetail[]required

The variants of the experiment, in a stable order

Item schema
itemsDaoExperimentVariantDetailrequired

A variant, with the name of the agent it runs resolved for display.

6 fields
idintegerrequired

The internal ID of the variant

namestringrequired

The name of the variant, which is the grouping key in reports

weightintegerrequired

The relative weight of the variant, not a percentage. (E.g., if two variants both have a weight of 10, they are equally likely to be selected.)

is_controlbooleanrequired

Whether this is the reference variant the others are measured against

agent_idintegerrequired

The agent this variant runs

agent_namestringrequired

The name of that agent

descriptionstring | nulloptional

The hypothesis under test

statusenum<string>required

draft, running, or stopped

Allowed values ["draft","running","stopped"]
started_atstring (date-time) | nulloptional

When the experiment started

stopped_atstring (date-time) | nulloptional

When the experiment stopped

created_atstring (date-time)required

When the experiment was created

updated_atstring (date-time)required

When the experiment was last written

last_updated_bystringrequired

Who last wrote it

targetDaoExperimentTargetSummary | nulloptional

The channel target being split, resolved for display. Null when the target has since been deleted, and when the read did not load it.

5 options
idintegerrequired

The internal ID of the channel target

targetstringrequired

The target itself, such as a phone number

target_modeenum<string>required

The mode of the channel target

Allowed values ["voice","chat","sms","email","whatsapp"]
channel_idintegerrequired

The channel the target belongs to

channel_namestringrequired

The name of that channel

pageintegerrequired

The page number of the results (0-based)

page_sizeintegerrequired

The number of items returned per page

total_pagesinteger | nulloptional

The total number of pages of results given the indicated page size

total_countinteger | nulloptional

The total number of items returned from the query

Response example
{
  "items": [
    {
      "id": 0,
      "name": "string",
      "target_id": "string",
      "variants": [
        {
          "id": 0,
          "name": "string",
          "weight": 0,
          "is_control": true,
          "agent_id": 0,
          "agent_name": "string"
        }
      ],
      "description": "string",
      "status": "string",
      "started_at": "string",
      "stopped_at": "string",
      "created_at": "string",
      "updated_at": "string",
      "last_updated_by": "string",
      "target": "string"
    }
  ],
  "page": 0,
  "page_size": 0,
  "total_pages": "string",
  "total_count": "string"
}
400Bad Request

No response body is declared.

422Validation Error

application/json

response HTTPValidationError required
1 field
detailValidationError[]optional
Item schema
itemsValidationErrorrequired
3 fields
locstring | integer[]required
Item schema
itemsstring | integerrequired
2 options
Option 1stringrequired
Option 2integerrequired
msgstringrequired
typestringrequired
Response example
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}