ClickStack: Create Saved Search

POST/v1/organizations/{organizationId}/services/{serviceId}/clickstack/saved-searches

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future.

ClickStack: Creates a new saved search.

Authorizations

Authorizationstringheaderrequired
Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi

Path parameters

organizationIdstringrequired
ID of the organization that owns the service.

format: uuid
serviceIdstringrequired
ID of the ClickStack service.

format: uuid

Request bodyJSON

namestringrequired
Display name for the saved search.

Example: "Production Errors"
sourceIdstringrequired
ID of the source to query. Must belong to the team.

Example: "507f1f77bcf86cd799439012"
selectoptionalstring
Comma-separated list of column expressions to display. Empty uses the source default.

Example: "Timestamp, ServiceName, Body"
whereoptionalstring
Row filter expression. The language is controlled by whereLanguage.

Example: "SeverityText:ERROR"
whereLanguageoptionalluceneorsql
Language used for the where filter.

Example: "lucene"
orderByoptionalstring
ORDER BY expression. Empty uses the source default.

Example: "Timestamp DESC"
tagsoptionalarray ofstring
Tags used to organize saved searches.

Example: ["production","errors"]
filtersoptionalarray ofobject
Structured pinned filters applied to the search.

Example: ["{\"type\":\"sql\",\"condition\":\"ServiceName IN ('checkout', 'payments')\"}"]
2 properties
- conditionstringrequired
  SQL predicate applied to the search, in <column> IN (...) form.
  
  Example: "ServiceName IN ('checkout', 'payments')"
- typeoptionalsql
  Always sql. Only SQL predicate filters render in the sidebar.
  
  Example: "sql"

Response

JSON

200

Successful response

JSON

statusoptionalnumber
HTTP status code.

Example: 200
requestIdoptionalstring
Unique id assigned to every request. UUIDv4

format: uuid
resultoptionalobject
12 properties
- idstringrequired
  Unique saved search ID. Server-generated.
  
  Example: "507f1f77bcf86cd799439011"
- namestringrequired
  Display name for the saved search.
  
  Example: "Production Errors"
- sourceIdstringrequired
  ID of the source this saved search queries.
  
  Example: "507f1f77bcf86cd799439012"
- selectoptionalstring
  Comma-separated list of column expressions to display. Empty uses the source default.
  
  Example: "Timestamp, ServiceName, Body"
- whereoptionalstring
  Row filter expression. The language is controlled by whereLanguage.
  
  Example: "SeverityText:ERROR"
- whereLanguageoptionalluceneorsql
  Language used for the where filter.
  
  Example: "lucene"
- orderByoptionalstring
  ORDER BY expression. Empty uses the source default.
  
  Example: "Timestamp DESC"
- tagsoptionalarray ofstring
  Tags used to organize saved searches.
  
  Example: ["production","errors"]
- filtersoptionalarray ofobject
  Structured pinned filters applied to the search.
  
  Example: ["{\"type\":\"sql\",\"condition\":\"ServiceName IN ('checkout', 'payments')\"}"]
  2 properties
  conditionstringrequired
  SQL predicate applied to the search, in <column> IN (...) form.
  
  Example: "ServiceName IN ('checkout', 'payments')"
  typeoptionalsql
  Always sql. Only SQL predicate filters render in the sidebar.
  
  Example: "sql"
- teamIdoptionalstring
  ID of the team that owns the saved search.
  
  Example: "507f1f77bcf86cd799439013"
- createdAtoptionalstring
  Creation timestamp.
  
  format: date-time
  Example: "2025-01-01T00:00:00.000Z"
- updatedAtoptionalstring
  Last update timestamp.
  
  format: date-time
  Example: "2025-06-15T10:30:00.000Z"

ClickStack: Create Saved Search

curl --request POST \
  --url https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/clickstack/saved-searches \
  --header 'Authorization: Basic <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "name": "Production Errors",
  "sourceId": "507f1f77bcf86cd799439012",
  "select": "Timestamp, ServiceName, Body",
  "where": "SeverityText:ERROR",
  "whereLanguage": "lucene",
  "orderBy": "Timestamp DESC",
  "tags": [
    "production",
    "errors"
  ],
  "filters": [
    "{\"type\":\"sql\",\"condition\":\"ServiceName IN ('checkout', 'payments')\"}"
  ]
}
EOF

const url = 'https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/clickstack/saved-searches';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Basic <token>'},
  body: JSON.stringify({
    name: 'Production Errors',
    sourceId: '507f1f77bcf86cd799439012',
    select: 'Timestamp, ServiceName, Body',
    where: 'SeverityText:ERROR',
    whereLanguage: 'lucene',
    orderBy: 'Timestamp DESC',
    tags: ['production', 'errors'],
    filters: ['{"type":"sql","condition":"ServiceName IN (\'checkout\', \'payments\')"}']
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/clickstack/saved-searches"

payload = {
    "name": "Production Errors",
    "sourceId": "507f1f77bcf86cd799439012",
    "select": "Timestamp, ServiceName, Body",
    "where": "SeverityText:ERROR",
    "whereLanguage": "lucene",
    "orderBy": "Timestamp DESC",
    "tags": ["production", "errors"],
    "filters": ["{\"type\":\"sql\",\"condition\":\"ServiceName IN ('checkout', 'payments')\"}"]
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic <token>"
}

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

print(response.text)

Response example

{
  "status": 200,
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "result": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Production Errors",
    "sourceId": "507f1f77bcf86cd799439012",
    "select": "Timestamp, ServiceName, Body",
    "where": "SeverityText:ERROR",
    "whereLanguage": "lucene",
    "orderBy": "Timestamp DESC",
    "tags": [
      "production",
      "errors"
    ],
    "filters": [
      "{\"type\":\"sql\",\"condition\":\"ServiceName IN ('checkout', 'payments')\"}"
    ],
    "teamId": "507f1f77bcf86cd799439013",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-06-15T10:30:00.000Z"
  }
}

{
  "status": 400,
  "error": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

{
  "status": 500,
  "error": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}