Measure

The measure endpoints are used for metric event collection and reporting for Searchcraft Cloud. If you are using Searchcraft Cloud and an SDK or CMS integration you do not need to use these endpoints directly. If you are using an API implementation these endpoints are available for use for capturing usage metrics.

API Endpoints

• GET /measure/status Returns whether the measurement system is enabled on this server instance ({ "enabled": true | false }). No authentication required. When enabled is false all other /measure/* endpoints are no-ops.
• POST /measure/event Records a single measurement event.
• POST /measure/batch Records multiple measurement events in a single request. All-or-nothing: if any event fails authorisation the entire batch is rejected.
• GET /measure/dashboard/summary Returns summary analytics including total searches, click-through rate, active users, and popular search terms.
• GET /measure/dashboard/conversion Returns conversion analytics including CTR chart data, popular/unpopular search terms with click positions, device breakdown, and session statistics.
• GET /measure/dashboard/usage Returns simple usage metrics for search query tracking and billing (total_searches and total_searches_in_billing_period).

The dashboard endpoints (/measure/dashboard/*) accept the following optional query parameters: organization_id, application_id, index_names (pipe-delimited, e.g. index1|index2), user_id, user_type, session_id, event_name, date_start (Unix timestamp), date_end (Unix timestamp), granularity (minutes | hours | days | weeks | months | years), rpp (results per page), page.

The following payload structure is used for measure event requests. /measure/event expects a single MeasureRequest object; /measure/batch expects { "items": [MeasureRequest, ...] }.

/**
 * The type representing a measure request.
 */
export interface MeasureRequest {
  event_name: MeasureEventName;
  properties: MeasureRequestProperties;
  user: MeasureRequestUser;
}

/**
 * Properties attached to a measure request.
 */
export interface MeasureRequestProperties {
  searchcraft_organization_id?: string;
  searchcraft_application_id?: string;
  searchcraft_federation_name?: string;
  searchcraft_index_names: string[];
  search_term?: string;
  search_kind?: string;
  ai_provider?: string;
  number_of_documents?: number;
  external_document_id?: string;
  document_position?: number;
  session_id?: string;
}

/**
 * User properties attached to a measure request.
 */
export interface MeasureRequestUser {
  user_id: string;
  country?: string;
  city?: string;
  device_id?: string;
  client_ip?: string;
  locale?: string;
  os?: string;
  platform?: string;
  region?: string;
  sdk_name?: string;
  sdk_version?: string;
  user_agent?: string;
  user_type?: "anonymous" | "authenticated";
  latitude?: number;
  longitude?: number;
}

Auth Requirement

Requires an authentication key that has ingestion permissions.

Self-Hosted Support

Self-hosted instances of Searchcraft may also make use of these endpoints but that involves setting up a Clickhouse cluster and configuring the Searchcraft instance to use it. Managing and hosting Clickhouse clusters are outside the scope of this documentation and are not supported by Searchcraft technical support.