cURL
curl --request POST \
--url https://search.glood.ai/api/storefront/v1/headless/filter-aggregations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-shop: <x-shop>' \
--data '
{
"collection": "<string>",
"tree": 123,
"query": "",
"applied_filters": [
{
"key": "<string>",
"value": [
"<string>"
],
"operator": "<string>"
}
],
"facets": [
{
"key": "<string>"
}
],
"locale": "en-US",
"market": 123,
"publication_ids": [
"30085840999"
],
"options": {
"include_zero_counts": false,
"include_disabled": false,
"sort_by": "count",
"limit": 20
},
"visitor_id": "<string>",
"client_id": "<string>",
"customer_id": "<string>"
}
'import requests
url = "https://search.glood.ai/api/storefront/v1/headless/filter-aggregations"
payload = {
"collection": "<string>",
"tree": 123,
"query": "",
"applied_filters": [
{
"key": "<string>",
"value": ["<string>"],
"operator": "<string>"
}
],
"facets": [{ "key": "<string>" }],
"locale": "en-US",
"market": 123,
"publication_ids": ["30085840999"],
"options": {
"include_zero_counts": False,
"include_disabled": False,
"sort_by": "count",
"limit": 20
},
"visitor_id": "<string>",
"client_id": "<string>",
"customer_id": "<string>"
}
headers = {
"x-shop": "<x-shop>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-shop': '<x-shop>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
collection: '<string>',
tree: 123,
query: '',
applied_filters: [{key: '<string>', value: ['<string>'], operator: '<string>'}],
facets: [{key: '<string>'}],
locale: 'en-US',
market: 123,
publication_ids: ['30085840999'],
options: {
include_zero_counts: false,
include_disabled: false,
sort_by: 'count',
limit: 20
},
visitor_id: '<string>',
client_id: '<string>',
customer_id: '<string>'
})
};
fetch('https://search.glood.ai/api/storefront/v1/headless/filter-aggregations', 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://search.glood.ai/api/storefront/v1/headless/filter-aggregations",
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([
'collection' => '<string>',
'tree' => 123,
'query' => '',
'applied_filters' => [
[
'key' => '<string>',
'value' => [
'<string>'
],
'operator' => '<string>'
]
],
'facets' => [
[
'key' => '<string>'
]
],
'locale' => 'en-US',
'market' => 123,
'publication_ids' => [
'30085840999'
],
'options' => [
'include_zero_counts' => false,
'include_disabled' => false,
'sort_by' => 'count',
'limit' => 20
],
'visitor_id' => '<string>',
'client_id' => '<string>',
'customer_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"x-shop: <x-shop>"
],
]);
$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://search.glood.ai/api/storefront/v1/headless/filter-aggregations"
payload := strings.NewReader("{\n \"collection\": \"<string>\",\n \"tree\": 123,\n \"query\": \"\",\n \"applied_filters\": [\n {\n \"key\": \"<string>\",\n \"value\": [\n \"<string>\"\n ],\n \"operator\": \"<string>\"\n }\n ],\n \"facets\": [\n {\n \"key\": \"<string>\"\n }\n ],\n \"locale\": \"en-US\",\n \"market\": 123,\n \"publication_ids\": [\n \"30085840999\"\n ],\n \"options\": {\n \"include_zero_counts\": false,\n \"include_disabled\": false,\n \"sort_by\": \"count\",\n \"limit\": 20\n },\n \"visitor_id\": \"<string>\",\n \"client_id\": \"<string>\",\n \"customer_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-shop", "<x-shop>")
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://search.glood.ai/api/storefront/v1/headless/filter-aggregations")
.header("x-shop", "<x-shop>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"collection\": \"<string>\",\n \"tree\": 123,\n \"query\": \"\",\n \"applied_filters\": [\n {\n \"key\": \"<string>\",\n \"value\": [\n \"<string>\"\n ],\n \"operator\": \"<string>\"\n }\n ],\n \"facets\": [\n {\n \"key\": \"<string>\"\n }\n ],\n \"locale\": \"en-US\",\n \"market\": 123,\n \"publication_ids\": [\n \"30085840999\"\n ],\n \"options\": {\n \"include_zero_counts\": false,\n \"include_disabled\": false,\n \"sort_by\": \"count\",\n \"limit\": 20\n },\n \"visitor_id\": \"<string>\",\n \"client_id\": \"<string>\",\n \"customer_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://search.glood.ai/api/storefront/v1/headless/filter-aggregations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-shop"] = '<x-shop>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"collection\": \"<string>\",\n \"tree\": 123,\n \"query\": \"\",\n \"applied_filters\": [\n {\n \"key\": \"<string>\",\n \"value\": [\n \"<string>\"\n ],\n \"operator\": \"<string>\"\n }\n ],\n \"facets\": [\n {\n \"key\": \"<string>\"\n }\n ],\n \"locale\": \"en-US\",\n \"market\": 123,\n \"publication_ids\": [\n \"30085840999\"\n ],\n \"options\": {\n \"include_zero_counts\": false,\n \"include_disabled\": false,\n \"sort_by\": \"count\",\n \"limit\": 20\n },\n \"visitor_id\": \"<string>\",\n \"client_id\": \"<string>\",\n \"customer_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"aggregations": {
"color": {
"type": "terms",
"data_type": "option",
"buckets": [
{ "value": "red", "label": "Red", "count": 42, "enabled": true, "is_others": false },
{ "value": "blue", "label": "Blue", "count": 30, "enabled": true, "is_others": false }
],
"has_more": false,
"other_count": 0
},
"price": {
"type": "range",
"data_type": "price",
"buckets": [ { "value": "0-50", "label": "$0 – $50", "count": 100 } ],
"stats": { "min": 5, "max": 499, "avg": 60, "sum": 14400, "count": 240 }
}
},
"facets": [
{ "id": 1, "key": "color", "title": "Color", "data_type": "option", "attribute_type": "option" },
{ "id": 2, "key": "price", "title": "Price", "data_type": "number", "attribute_type": "price" }
],
"tree": { "id": 5, "target_page": "search", "target_id": 10, "is_default": false },
"metadata": { "total_products": 240, "query_time": 30, "region": "toronto" }
}
{
"error": [
{
"message": "\"applied_filters[0].key\" is required",
"path": ["applied_filters", 0, "key"],
"type": "any.required",
"context": { "label": "applied_filters[0].key", "key": "key" }
}
],
"ok": false
}
Headless APIs
Filter Aggregations
Live Elasticsearch facet counts for a given query + applied filters. Auth: Authorization: Bearer <gl_sf_...> + x-shop.
POST
/
api
/
storefront
/
v1
/
headless
/
filter-aggregations
cURL
curl --request POST \
--url https://search.glood.ai/api/storefront/v1/headless/filter-aggregations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'x-shop: <x-shop>' \
--data '
{
"collection": "<string>",
"tree": 123,
"query": "",
"applied_filters": [
{
"key": "<string>",
"value": [
"<string>"
],
"operator": "<string>"
}
],
"facets": [
{
"key": "<string>"
}
],
"locale": "en-US",
"market": 123,
"publication_ids": [
"30085840999"
],
"options": {
"include_zero_counts": false,
"include_disabled": false,
"sort_by": "count",
"limit": 20
},
"visitor_id": "<string>",
"client_id": "<string>",
"customer_id": "<string>"
}
'import requests
url = "https://search.glood.ai/api/storefront/v1/headless/filter-aggregations"
payload = {
"collection": "<string>",
"tree": 123,
"query": "",
"applied_filters": [
{
"key": "<string>",
"value": ["<string>"],
"operator": "<string>"
}
],
"facets": [{ "key": "<string>" }],
"locale": "en-US",
"market": 123,
"publication_ids": ["30085840999"],
"options": {
"include_zero_counts": False,
"include_disabled": False,
"sort_by": "count",
"limit": 20
},
"visitor_id": "<string>",
"client_id": "<string>",
"customer_id": "<string>"
}
headers = {
"x-shop": "<x-shop>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-shop': '<x-shop>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
collection: '<string>',
tree: 123,
query: '',
applied_filters: [{key: '<string>', value: ['<string>'], operator: '<string>'}],
facets: [{key: '<string>'}],
locale: 'en-US',
market: 123,
publication_ids: ['30085840999'],
options: {
include_zero_counts: false,
include_disabled: false,
sort_by: 'count',
limit: 20
},
visitor_id: '<string>',
client_id: '<string>',
customer_id: '<string>'
})
};
fetch('https://search.glood.ai/api/storefront/v1/headless/filter-aggregations', 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://search.glood.ai/api/storefront/v1/headless/filter-aggregations",
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([
'collection' => '<string>',
'tree' => 123,
'query' => '',
'applied_filters' => [
[
'key' => '<string>',
'value' => [
'<string>'
],
'operator' => '<string>'
]
],
'facets' => [
[
'key' => '<string>'
]
],
'locale' => 'en-US',
'market' => 123,
'publication_ids' => [
'30085840999'
],
'options' => [
'include_zero_counts' => false,
'include_disabled' => false,
'sort_by' => 'count',
'limit' => 20
],
'visitor_id' => '<string>',
'client_id' => '<string>',
'customer_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"x-shop: <x-shop>"
],
]);
$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://search.glood.ai/api/storefront/v1/headless/filter-aggregations"
payload := strings.NewReader("{\n \"collection\": \"<string>\",\n \"tree\": 123,\n \"query\": \"\",\n \"applied_filters\": [\n {\n \"key\": \"<string>\",\n \"value\": [\n \"<string>\"\n ],\n \"operator\": \"<string>\"\n }\n ],\n \"facets\": [\n {\n \"key\": \"<string>\"\n }\n ],\n \"locale\": \"en-US\",\n \"market\": 123,\n \"publication_ids\": [\n \"30085840999\"\n ],\n \"options\": {\n \"include_zero_counts\": false,\n \"include_disabled\": false,\n \"sort_by\": \"count\",\n \"limit\": 20\n },\n \"visitor_id\": \"<string>\",\n \"client_id\": \"<string>\",\n \"customer_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-shop", "<x-shop>")
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://search.glood.ai/api/storefront/v1/headless/filter-aggregations")
.header("x-shop", "<x-shop>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"collection\": \"<string>\",\n \"tree\": 123,\n \"query\": \"\",\n \"applied_filters\": [\n {\n \"key\": \"<string>\",\n \"value\": [\n \"<string>\"\n ],\n \"operator\": \"<string>\"\n }\n ],\n \"facets\": [\n {\n \"key\": \"<string>\"\n }\n ],\n \"locale\": \"en-US\",\n \"market\": 123,\n \"publication_ids\": [\n \"30085840999\"\n ],\n \"options\": {\n \"include_zero_counts\": false,\n \"include_disabled\": false,\n \"sort_by\": \"count\",\n \"limit\": 20\n },\n \"visitor_id\": \"<string>\",\n \"client_id\": \"<string>\",\n \"customer_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://search.glood.ai/api/storefront/v1/headless/filter-aggregations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-shop"] = '<x-shop>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"collection\": \"<string>\",\n \"tree\": 123,\n \"query\": \"\",\n \"applied_filters\": [\n {\n \"key\": \"<string>\",\n \"value\": [\n \"<string>\"\n ],\n \"operator\": \"<string>\"\n }\n ],\n \"facets\": [\n {\n \"key\": \"<string>\"\n }\n ],\n \"locale\": \"en-US\",\n \"market\": 123,\n \"publication_ids\": [\n \"30085840999\"\n ],\n \"options\": {\n \"include_zero_counts\": false,\n \"include_disabled\": false,\n \"sort_by\": \"count\",\n \"limit\": 20\n },\n \"visitor_id\": \"<string>\",\n \"client_id\": \"<string>\",\n \"customer_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"aggregations": {
"color": {
"type": "terms",
"data_type": "option",
"buckets": [
{ "value": "red", "label": "Red", "count": 42, "enabled": true, "is_others": false },
{ "value": "blue", "label": "Blue", "count": 30, "enabled": true, "is_others": false }
],
"has_more": false,
"other_count": 0
},
"price": {
"type": "range",
"data_type": "price",
"buckets": [ { "value": "0-50", "label": "$0 – $50", "count": 100 } ],
"stats": { "min": 5, "max": 499, "avg": 60, "sum": 14400, "count": 240 }
}
},
"facets": [
{ "id": 1, "key": "color", "title": "Color", "data_type": "option", "attribute_type": "option" },
{ "id": 2, "key": "price", "title": "Price", "data_type": "number", "attribute_type": "price" }
],
"tree": { "id": 5, "target_page": "search", "target_id": 10, "is_default": false },
"metadata": { "total_products": 240, "query_time": 30, "region": "toronto" }
}
{
"error": [
{
"message": "\"applied_filters[0].key\" is required",
"path": ["applied_filters", 0, "key"],
"type": "any.required",
"context": { "label": "applied_filters[0].key", "key": "key" }
}
],
"ok": false
}
{
"aggregations": {
"color": {
"type": "terms",
"data_type": "option",
"buckets": [
{ "value": "red", "label": "Red", "count": 42, "enabled": true, "is_others": false },
{ "value": "blue", "label": "Blue", "count": 30, "enabled": true, "is_others": false }
],
"has_more": false,
"other_count": 0
},
"price": {
"type": "range",
"data_type": "price",
"buckets": [ { "value": "0-50", "label": "$0 – $50", "count": 100 } ],
"stats": { "min": 5, "max": 499, "avg": 60, "sum": 14400, "count": 240 }
}
},
"facets": [
{ "id": 1, "key": "color", "title": "Color", "data_type": "option", "attribute_type": "option" },
{ "id": 2, "key": "price", "title": "Price", "data_type": "number", "attribute_type": "price" }
],
"tree": { "id": 5, "target_page": "search", "target_id": 10, "is_default": false },
"metadata": { "total_products": 240, "query_time": 30, "region": "toronto" }
}
{
"error": [
{
"message": "\"applied_filters[0].key\" is required",
"path": ["applied_filters", 0, "key"],
"type": "any.required",
"context": { "label": "applied_filters[0].key", "key": "key" }
}
],
"ok": false
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Shopify store URL. Resolves the shop for the request (headless does not accept ?shop=).
Example:
"shop.myshopify.com"
Body
application/json
Request body
Live Elasticsearch facet counts for a query + applied filters.
Collection id to scope aggregation. String or integer.
Explicit filter tree id.
Search term to aggregate against. May be empty.
Currently applied filter selections.
Show child attributes
Show child attributes
Which facets to aggregate.
Show child attributes
Show child attributes
BCP-47 locale.
Shopify market id.
Optional. Numeric Shopify publication (sales channel) ids. When present, only products published on at least one of these channels are returned and the default "published to the Online Store" gate is replaced by this filter; market and B2B filters still apply. A single id may be sent without the array wrapper. Each id must be one the merchant enabled under Settings → Sales channels; unknown ids return 400. The id is the numeric tail of gid://shopify/Publication/.
Maximum array length:
50Pattern:
^[0-9]+$Example:
["30085840999"]
Aggregation options.
Show child attributes
Show child attributes
Anonymous device/browser UID (the gl_s_uid cookie). The primary personalization key; stays stable when a customer logs in.
Per-session / per-device identifier.
Shopify customer id. Present only when the shopper is logged in; enables customer-level personalization.
Response
Filter aggregations
Live facet counts (buckets + stats) for the current query and applied filters.
Was this page helpful?