Cluster Operations
AI agents and LLMs: before exploring further, fetch the full index of Typesense documentation with descriptions at https://typesense.org/docs/llms.txt.
Create Snapshot (for backups)
Creates a point-in-time snapshot of a Typesense node's state and data in the specified directory.
You can then backup the snapshot directory that gets created and later restore it as a data directory, as needed.
Sample Response
Definition
POST ${TYPESENSE_HOST}/operations/snapshot
Arguments
| Parameter | Required | Description |
|---|---|---|
| snapshot_path | no | The directory on the server where the snapshot should be saved. If not provided, Typesense will perform an internal snapshot to compact Raft logs into the snapshot internally, without exporting the data out of the Typesense process. This is helpful during certain scenarios when recovering a node in an HA cluster. |
Compacting the on-disk database
Typesense uses RocksDB to store your documents on the disk. If you do frequent writes or updates, you could benefit from running a compaction of the underlying RocksDB database. This could reduce the size of the database and decrease read latency.
While the database will not block during this operation, we recommend running it during off-peak hours.
curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -X POST http://localhost:8108/operations/db/compactDefinition
POST ${TYPESENSE_HOST}/operations/db/compact
Re-elect Leader
Triggers a follower node to initiate the raft voting process, which triggers leader re-election.
The follower node that you run this operation against will become the new leader, once this command succeeds.
Sample Response
Definition
POST ${TYPESENSE_HOST}/operations/vote
Toggle Slow Request Log
Enable logging of requests that take over a defined threshold of time.
Default: -1 which disables slow request logging.
Slow requests are logged to the primary log file, with the prefix SLOW REQUEST.
Sample Response
Definition
POST ${TYPESENSE_HOST}/config
Clear cache
Responses of search requests that are sent with use_cache parameter are cached in a LRU cache. To clear this cache completely:
curl -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -X POST \
http://localhost:8108/operations/cache/clearDefinition
POST ${TYPESENSE_HOST}/operations/cache/clear
Cluster Metrics
Get current RAM, CPU, Disk & Network usage metrics.
Sample Response
Metrics Reference
System Metrics
| Metric | Description |
|---|---|
system_cpu_active_percentage | Overall CPU usage across all cores. |
system_cpuN_active_percentage | CPU usage for individual core N (e.g. system_cpu1_active_percentage). |
system_disk_total_bytes | Total disk space in bytes. |
system_disk_used_bytes | Used disk space in bytes. |
system_memory_total_bytes | Total system RAM in bytes. |
system_memory_used_bytes | Used system RAM in bytes. |
system_memory_total_swap_bytes | Total swap space in bytes. |
system_memory_used_swap_bytes | Used swap space in bytes. |
system_network_received_bytes | Network bytes received. |
system_network_sent_bytes | Network bytes sent. |
Typesense Memory Metrics
These metrics are sourced from jemalloc, the memory allocator used by Typesense.
| Metric | Description |
|---|---|
typesense_memory_allocated_bytes | Total bytes currently allocated by the Typesense process. This is the most direct measure of how much memory Typesense is actively using. Corresponds to jemalloc's stats.allocated. |
typesense_memory_active_bytes | Total bytes in active memory pages allocated by the Typesense process. This is a multiple of the page size and is always >= allocated_bytes. Corresponds to jemalloc's stats.active. |
typesense_memory_fragmentation_ratio | Fraction of active memory that is fragmented, calculated as 1 - (allocated_bytes / active_bytes). Values close to 0 indicate low fragmentation; higher values indicate more wasted space within active pages. |
typesense_memory_mapped_bytes | Total bytes in virtual address space mapped by the allocator. Larger than active_bytes as it includes all mapped extents. Corresponds to jemalloc's stats.mapped. |
typesense_memory_metadata_bytes | Bytes used by the memory allocator for its own internal bookkeeping and metadata structures. Corresponds to jemalloc's stats.metadata. |
typesense_memory_resident_bytes | Total bytes physically resident in RAM. Includes metadata pages, active allocation pages, and unused dirty pages. Corresponds to jemalloc's stats.resident. |
typesense_memory_retained_bytes | Total bytes in virtual memory mappings retained by the allocator rather than returned to the OS. This memory is not necessarily backed by physical RAM. Corresponds to jemalloc's stats.retained. |
Definition
GET ${TYPESENSE_HOST}/metrics.json
Prometheus Integration
If you use Prometheus, here's a community-maintained project that lets you periodically poll this endpoint and export the data into Prometheus:
API Stats
Get stats about API endpoints.
This endpoint returns average requests per second and latencies for all requests in the last 10 seconds.
Sample Response
Definition
GET ${TYPESENSE_HOST}/stats.json
Prometheus Integration
If you use Prometheus, here's a community-maintained project that lets you periodically poll this endpoint and export the data into Prometheus:
Health
Get health information about a Typesense node.
Sample Response
When a node is running out of memory / disk, the API response will have an additional resource_error field that's set to either OUT_OF_DISK or OUT_OF_MEMORY.
Definition
GET ${TYPESENSE_HOST}/health
Debug
Get debugging information about a Typesense node.
Sample Response
version is the version of Typesense you're running.
You can determine whether a node is a leader or follower by the value of the state field:
| State | Role |
|---|---|
| 1 | LEADER |
| 4 | FOLLOWER |
Definition
GET ${TYPESENSE_HOST}/debug