Create a custom result query

curl --request POST \
  --url https://api.abconvert.io/v1/experiments/{id}/results \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "breakdown": [
    "country"
  ],
  "product_group_id": "<string>"
}
'

import requests

url = "https://api.abconvert.io/v1/experiments/{id}/results"

payload = {
    "breakdown": ["country"],
    "product_group_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({breakdown: ['country'], product_group_id: '<string>'})
};

fetch('https://api.abconvert.io/v1/experiments/{id}/results', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.abconvert.io/v1/experiments/{id}/results",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'breakdown' => [
        'country'
    ],
    'product_group_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.abconvert.io/v1/experiments/{id}/results"

	payload := strings.NewReader("{\n  \"breakdown\": [\n    \"country\"\n  ],\n  \"product_group_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.abconvert.io/v1/experiments/{id}/results")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"breakdown\": [\n    \"country\"\n  ],\n  \"product_group_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.abconvert.io/v1/experiments/{id}/results")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"breakdown\": [\n    \"country\"\n  ],\n  \"product_group_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "object": "results_query",
  "id": "66d3b91c4f2a7e5081c9a3b7",
  "experiment_id": "3021",
  "status": "pending",
  "failure_reason": "<string>",
  "computed_at": "2023-11-07T05:31:56Z",
  "test_groups": [
    {
      "test_group_index": 1,
      "sample_size": 5231,
      "session_count": 6816,
      "conversion_rate": 0.034,
      "revenue_per_visitor": {
        "amount": "17.99",
        "currency": "USD"
      },
      "average_order_value": {
        "amount": "17.99",
        "currency": "USD"
      },
      "profit_per_visitor": {
        "amount": "17.99",
        "currency": "USD"
      },
      "add_to_cart_rate": 0.081,
      "reached_checkout_rate": 0.052,
      "orders": 179,
      "revenue": {
        "amount": "17.99",
        "currency": "USD"
      }
    }
  ],
  "breakdown": {
    "dimensions": [
      "country"
    ],
    "rows": [
      {
        "test_group_index": 1,
        "sample_size": 5231,
        "dimension_value": "US::Mobile",
        "session_count": 6816,
        "conversion_rate": 0.034,
        "revenue_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "average_order_value": {
          "amount": "17.99",
          "currency": "USD"
        },
        "profit_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "add_to_cart_rate": 0.081,
        "reached_checkout_rate": 0.052,
        "orders": 179,
        "revenue": {
          "amount": "17.99",
          "currency": "USD"
        }
      }
    ]
  }
}

{
  "object": "results_query",
  "id": "66d3b91c4f2a7e5081c9a3b7",
  "experiment_id": "3021",
  "status": "pending",
  "failure_reason": "<string>",
  "computed_at": "2023-11-07T05:31:56Z",
  "test_groups": [
    {
      "test_group_index": 1,
      "sample_size": 5231,
      "session_count": 6816,
      "conversion_rate": 0.034,
      "revenue_per_visitor": {
        "amount": "17.99",
        "currency": "USD"
      },
      "average_order_value": {
        "amount": "17.99",
        "currency": "USD"
      },
      "profit_per_visitor": {
        "amount": "17.99",
        "currency": "USD"
      },
      "add_to_cart_rate": 0.081,
      "reached_checkout_rate": 0.052,
      "orders": 179,
      "revenue": {
        "amount": "17.99",
        "currency": "USD"
      }
    }
  ],
  "breakdown": {
    "dimensions": [
      "country"
    ],
    "rows": [
      {
        "test_group_index": 1,
        "sample_size": 5231,
        "dimension_value": "US::Mobile",
        "session_count": 6816,
        "conversion_rate": 0.034,
        "revenue_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "average_order_value": {
          "amount": "17.99",
          "currency": "USD"
        },
        "profit_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "add_to_cart_rate": 0.081,
        "reached_checkout_rate": 0.052,
        "orders": 179,
        "revenue": {
          "amount": "17.99",
          "currency": "USD"
        }
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

Results

Create a custom result query

Creates a custom result query, or reuses one already computed. Beta.

Every field is optional; an empty body asks the same question the snapshot read answers. Unlike that read, this one can group by any dimension, narrow the window, and scope to a product group.

Not real time. A query matching one computed within the last hour returns that snapshot with the same id and no recomputation, and a query identical to one already running attaches to it rather than starting a second. So results can be up to an hour old, and polling faster than that changes nothing.

Answers 200 when a computed snapshot already covers the query and 202 when one is being computed. Either way the body identifies the query and carries no rows: read those from GET /experiments/{id}/results/{query_id}.

A test that has not run yet returns 422 results_not_available: there is no traffic to compute from until it starts.

This is a read: it derives from data you already have and changes nothing, so a read_experiments token may call it.

POST

experiments

{id}

results

Create a custom result query

curl --request POST \
  --url https://api.abconvert.io/v1/experiments/{id}/results \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "breakdown": [
    "country"
  ],
  "product_group_id": "<string>"
}
'

import requests

url = "https://api.abconvert.io/v1/experiments/{id}/results"

payload = {
    "breakdown": ["country"],
    "product_group_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({breakdown: ['country'], product_group_id: '<string>'})
};

fetch('https://api.abconvert.io/v1/experiments/{id}/results', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.abconvert.io/v1/experiments/{id}/results",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'breakdown' => [
        'country'
    ],
    'product_group_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.abconvert.io/v1/experiments/{id}/results"

	payload := strings.NewReader("{\n  \"breakdown\": [\n    \"country\"\n  ],\n  \"product_group_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.abconvert.io/v1/experiments/{id}/results")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"breakdown\": [\n    \"country\"\n  ],\n  \"product_group_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.abconvert.io/v1/experiments/{id}/results")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"breakdown\": [\n    \"country\"\n  ],\n  \"product_group_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "object": "results_query",
  "id": "66d3b91c4f2a7e5081c9a3b7",
  "experiment_id": "3021",
  "status": "pending",
  "failure_reason": "<string>",
  "computed_at": "2023-11-07T05:31:56Z",
  "test_groups": [
    {
      "test_group_index": 1,
      "sample_size": 5231,
      "session_count": 6816,
      "conversion_rate": 0.034,
      "revenue_per_visitor": {
        "amount": "17.99",
        "currency": "USD"
      },
      "average_order_value": {
        "amount": "17.99",
        "currency": "USD"
      },
      "profit_per_visitor": {
        "amount": "17.99",
        "currency": "USD"
      },
      "add_to_cart_rate": 0.081,
      "reached_checkout_rate": 0.052,
      "orders": 179,
      "revenue": {
        "amount": "17.99",
        "currency": "USD"
      }
    }
  ],
  "breakdown": {
    "dimensions": [
      "country"
    ],
    "rows": [
      {
        "test_group_index": 1,
        "sample_size": 5231,
        "dimension_value": "US::Mobile",
        "session_count": 6816,
        "conversion_rate": 0.034,
        "revenue_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "average_order_value": {
          "amount": "17.99",
          "currency": "USD"
        },
        "profit_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "add_to_cart_rate": 0.081,
        "reached_checkout_rate": 0.052,
        "orders": 179,
        "revenue": {
          "amount": "17.99",
          "currency": "USD"
        }
      }
    ]
  }
}

{
  "object": "results_query",
  "id": "66d3b91c4f2a7e5081c9a3b7",
  "experiment_id": "3021",
  "status": "pending",
  "failure_reason": "<string>",
  "computed_at": "2023-11-07T05:31:56Z",
  "test_groups": [
    {
      "test_group_index": 1,
      "sample_size": 5231,
      "session_count": 6816,
      "conversion_rate": 0.034,
      "revenue_per_visitor": {
        "amount": "17.99",
        "currency": "USD"
      },
      "average_order_value": {
        "amount": "17.99",
        "currency": "USD"
      },
      "profit_per_visitor": {
        "amount": "17.99",
        "currency": "USD"
      },
      "add_to_cart_rate": 0.081,
      "reached_checkout_rate": 0.052,
      "orders": 179,
      "revenue": {
        "amount": "17.99",
        "currency": "USD"
      }
    }
  ],
  "breakdown": {
    "dimensions": [
      "country"
    ],
    "rows": [
      {
        "test_group_index": 1,
        "sample_size": 5231,
        "dimension_value": "US::Mobile",
        "session_count": 6816,
        "conversion_rate": 0.034,
        "revenue_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "average_order_value": {
          "amount": "17.99",
          "currency": "USD"
        },
        "profit_per_visitor": {
          "amount": "17.99",
          "currency": "USD"
        },
        "add_to_cart_rate": 0.081,
        "reached_checkout_rate": 0.052,
        "orders": 179,
        "revenue": {
          "amount": "17.99",
          "currency": "USD"
        }
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "request_id": "<string>",
    "details": {},
    "findings": [
      {
        "severity": "error",
        "code": "product_not_found",
        "message": "<string>",
        "param": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Bearer tokens created in the ABConvert admin under Settings → MCP & API Access. Scopes: read_experiments and write_experiments (write implies read; the default is read). See Authentication for which scope each request needs.

Path Parameters

string

required

The test's numeric ID as a string, for example "3021".

Pattern: ^[0-9]+$

Example:

"3021"

Body

application/json

breakdown

enum<string>[]

Group the rows by one or two dimensions. Order doesn't matter: it names a query, and the same pair in either order is the same query. Naming the same dimension twice returns 422 duplicate_breakdown_dimension. Grouping by product_id also needs product_group_id (that group is what the products are resolved from), and without it the request returns 422 product_id_requires_product_group.

Required array length: 1 - 2 elements

A dimension a custom result query can group by. product_id requires product_group_id, which scopes it to that product group's products.

Available options:

date,

country,

market,

device,

visitor_type,

traffic_channel,

traffic_platform,

referral_domain,

landing_page,

utm_source,

utm_medium,

utm_campaign,

utm_term,

utm_content,

product_id

sample_basis

enum<string>

Which visitors count. assignment includes every visitor put in a test group; exposure only those the test actually reached. exposure is only available on tests measured that way; asking for it elsewhere returns 422 sample_basis_unsupported.

Available options:

assignment,

exposure

product_group_id

string

Scope the query to one product group. Read the id from a test's product_group; any other value returns 422 product_group_not_found.

Pattern: ^[a-fA-F0-9]{24}$

date_range

object

Inclusive window, both bounds required. Defaults to the test's own lifetime. An unknown key here returns 422 invalid_date_range.

The window is narrowed to the days that can hold data: no earlier than the day the test started, no later than today. Asking for more isn't an error. The window isn't narrowed to the day the test ended: orders count on the day they were placed, so a window past the end date picks up conversions from visitors assigned before it.

A window that can hold nothing at all (ending before the test started, or beginning after today) returns 422 date_range_out_of_bounds.

Show child attributes

Response

A computed snapshot already answers this query.

A custom result query job. Beta.

status is pending until the snapshot is computed, then completed or failed. The result fields are present only when completed.

object

string

required

Allowed value: "results_query"

string

required

Treat as opaque. Never parse it.

Example:

"66d3b91c4f2a7e5081c9a3b7"

experiment_id

string

required

Example:

"3021"

status

enum<string>

required

Available options:

pending,

completed,

failed

failure_reason

string | null

Why the query failed, in plain language. Present only when status is failed. Run the query again; if it fails again, send support this text and the query id.

computed_at

string<date-time> | null

test_groups

object[]

Whole-test totals. Present on a query with no breakdown; a dimensional query answers with breakdown.rows instead, and carries no separate totals.

Show child attributes

breakdown

object | null

Present when the query named a breakdown.

Show child attributes

⌘I

Overview

Tests

Lifecycle

Schedule

Results

Exports

Create a custom result query

Authorizations

Path Parameters

Body

Response