Indexing
Health
https://searcio.com/api/v1
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
One endpoint that plugins use to verify a connection and read a site's live status and quota. It is authenticated with the write credentials, because it exposes usage data.
Base: https://searcio.com/api/v1/sites/{site}, or key-relative
https://searcio.com/api/v1. In the key-relative form the site is
resolved from the write key, and site.id in the response gives you its id
without asking the user.
GET /health
Request
GET /api/v1/sites/123/health
X-Write-Key: wk_live_abc
X-Write-Secret: ••••••Response: 200 OK
{
"site": {
"id": 123,
"name": "Acme Store",
"status": "connected",
"platform": "woocommerce",
"last_synced_at": "2026-06-23T09:12:44+00:00",
"statistics_url": "https://searcio.com/acme/sites/123"
},
"account": {
"served": true,
"reason": null,
"support_url": "https://searcio.com/acme/support"
},
"usage": {
"searches": { "used": 8123, "limit": 100000, "percent": 8, "exceeded": false, "near_limit": false },
"ai_messages": { "used": 180, "limit": 500, "percent": 36, "exceeded": false, "near_limit": false },
"documents": { "used": 12450, "limit": 50000, "percent": 24, "exceeded": false, "near_limit": false, "indexed": 4120 },
"sites": { "used": 2, "limit": 5, "percent": 40, "exceeded": false, "near_limit": false },
"members": { "used": 3, "limit": 5, "percent": 60, "exceeded": false, "near_limit": false }
},
"plan": {
"id": 4,
"slug": "starter",
"name": "Starter",
"is_free": false,
"upgrade_url": "https://searcio.com/acme/billing",
"languages": { "limit": 3, "allowed": ["de", "en"] }
},
"engine": { "reachable": true },
"version": "v1"
}Fields
| Field | Meaning |
|---|---|
site.status |
pending, connected or disabled. |
site.last_synced_at |
When the last successful indexing run finished (ISO 8601), or null. |
site.statistics_url |
Absolute link to this site's search statistics in the dashboard, so a plugin can link straight to them. |
account.served |
Whether searching and indexing are served. false when the account has no active plan or is suspended. |
account.reason |
Why not: no_active_plan, payment_overdue or account_suspended, or null when the account is served. It is the same reason a refused call returns. See Errors. |
account.support_url |
Absolute link to the account's support page in the dashboard, in every account state, so a plugin can offer "Contact support" for a suspended account. |
usage.* |
For each metric: used, limit (null means unlimited), percent, exceeded and near_limit (80% or more). Without an active plan every limit is 0, except ai_messages, which keeps the platform cap. |
usage.documents.indexed |
How many documents this site's search index holds right now, counted live. used is the account's counter across all its sites and is only as fresh as the last sync, so after a rebuild went wrong the two can differ. 0 means the index is empty or missing: run a full sync. null when the engine is unreachable. |
plan.id / slug / name |
The account's current plan, or null if it has none. name is localized. |
plan.is_free |
true when the account is on a free plan, a good moment to suggest an upgrade in your plugin. |
plan.upgrade_url |
Absolute link to the customer's billing page, so a plugin can link to "Upgrade your plan". |
plan.languages |
The plan's languages: limit (null means unlimited) and the site's enabled languages (allowed; empty means unrestricted). See Documents. |
engine.reachable |
Whether the search engine is reachable. |
version |
API version. |
Errors
| Status | When |
|---|---|
401 |
Missing or invalid write credentials, or an unknown site id (the two are deliberately indistinguishable) |
403 |
Site disabled |
Health keeps answering 200 for an account that is not served, so a plugin can
show the state from account instead of an error.
How plugins use it
flowchart TD
A["User clicks 'Test connection'"] --> B["GET /health with entered keys"]
B -- 200 --> C["Show ✓ Connected<br/>+ 'X / Y documents indexed'"]
B -- "200, account.served false" --> F["Show ✗ No active plan / suspended<br/>+ link to plan.upgrade_url"]
B -- 401 --> D["Show ✗ Invalid credentials"]
B -- 403 --> E["Show ✗ Site disabled"]Recommended uses:
- Validate on save. When a user pastes credentials into your plugin's
settings, call
/healthbefore saving them and show a clear ✓ or ✗. - Status widget. Display "Connected · 12,450 / 50,000 documents · last
synced 5 min ago" from
usage.documentsandlast_synced_at. - Check before a large sync. Read
usage.documentsand warn the user if the catalogue would exceed thelimit, rather than meeting a429halfway through. - Search engine availability. If
engine.reachableisfalse, show a degraded state and rely on the platform's own search until it recovers. - Upgrade prompt. When
plan.is_freeistrue, show an "Upgrade for more capacity" link toplan.upgrade_url.