​

Read Search Analytics — top queries, zero-result, click-through

​

What Search Analytics measures

​

Reading the dashboard

• Top queries by volume is the ground truth for what your team is actually looking for. If a surface you rely on (the messages hub, say) top-ranks on queries none of your dashboards surface, that is a coverage signal: the quick filters or saved views need to catch up to real behaviour.
• Zero-result is the most actionable panel. Every row is a query your team expected to match something and did not. Read it as a binary: either the data genuinely does not exist (nobody ever sent that campaign, so nothing is wrong) or the index is missing terms that should match (and the team keeps paying a search tax every day).
• Click-through and zero-result are the relationship to read together. A query with a high zero-result count and a low CTR is the classic “the search index misses common terms” symptom — people type something plausible, get nothing, and give up. A query with low zero-result count and low CTR is a ranking or snippet problem, not an index problem — the results exist, but the snippet does not earn the click.
• Parse failures is the lexicon and grammar signal. Every row is an input the search syntax rejected before it ever reached the index. A cluster of parse failures on phrases such as rma return label or ref: 1234 tells you the free-text-to-field mapping needs work — the team has settled on a convention (a return-merchandise-authorization code, an RMA dash format) that the grammar does not yet accept. This is the endpoint the operator points at when deciding whether to extend the keyword lexicon, add an alias, or fix the suggested-query examples in the search box.

​

Operator playbook — working a zero-result spike

• The phrase also shows up in Parse failures (with a representative raw sample like rma return label or rma:RMA-1234), meaning the search grammar rejected the input before it ever reached the index. The gap is in the grammar — the field prefix you need is not one the grammar recognizes, or the dash and slash characters in the convention are unsupported. Personal data is masked in the sample, so the row aggregates safely across customers.
• The phrase does not appear in parse failures — the query parsed fine, and the index genuinely did not match it. That narrows the fix to the index and the keyword lexicon that maps raw terms to fields, rather than the syntax itself.

• Register rma as an accepted field alias (alongside the surface it should search — typically the messages surface for a support note, or the contact surface for a return-owner lookup), so rma:RMA-1234 parses as a fielded clause.
• Add rma and rma return label as aliases for the existing return-reference field, so a free-text search mentioning the phrase resolves to the right indexed column rather than no column at all.
• If the phrase parses but keeps returning zero results, the lexicon is fine and the remediation is indexing the return-reference column on the surface the search hits (a conversation or message text field) rather than changing the grammar again.

1. Reopen the Click-through panel on the same 30d window and locate rma return label. The CTR should now rise toward the baseline of other fielded searches on that surface. On the pre-fix window, the query sat near zero CTR because the runs returned nothing; post-fix, the same inputs produce results and clicks.
2. Switch to the shorter 7d window to isolate the new traffic. The post-fix 7d window is the rolling confirmation: high CTR here, paired with a dropping zero-result count, proves the remediation is behaving. If the zero-result count stays flat on the new window even after the alias shipped, the alias did not register — recheck the operator-side change, or the index needs the new column indexed (Step 2, option three).

​

Using the API directly

curl "https://api.orbit.devotel.io/api/v1/search-analytics/top-queries?from=2026-08-01&to=2026-08-25&limit=5" \
  -H "X-API-Key: $ORBIT_API_KEY"

{
  "data": {
    "rows": [
      {
        "query_normalized": "status:failed",
        "count": 412,
        "surfaces": ["messages"],
        "avg_results": 18.4,
        "zero_result_count": 7,
        "last_seen_at": "2026-08-25T09:41:12.884Z"
      }
    ],
    "range": { "from": "2026-08-01T00:00:00.000Z", "to": "2026-08-25T23:59:59.999Z" }
  }
}

curl "https://api.orbit.devotel.io/api/v1/search-analytics/zero-result?from=2026-08-18&limit=5" \
  -H "X-API-Key: $ORBIT_API_KEY"

{
  "data": {
    "rows": [
      {
        "query_normalized": "rma return label",
        "count": 34,
        "surfaces": ["messages"],
        "last_seen_at": "2026-08-24T16:20:03.551Z"
      }
    ],
    "range": { "from": "2026-08-18T00:00:00.000Z", "to": "2026-08-25T23:59:59.999Z" }
  }
}

curl "https://api.orbit.devotel.io/api/v1/search-analytics/click-through?surface=messages&limit=5" \
  -H "X-API-Key: $ORBIT_API_KEY"

{
  "data": {
    "rows": [
      {
        "query_normalized": "status:failed",
        "count": 980,
        "click_count": 611,
        "ctr": 62.3,
        "surfaces": ["messages"],
        "last_seen_at": "2026-08-25T12:14:55.402Z"
      }
    ],
    "range": { "from": "2026-08-18T00:00:00.000Z", "to": "2026-08-25T23:59:59.999Z" }
  }
}

curl "https://api.orbit.devotel.io/api/v1/search-analytics/parse-failures?limit=5" \
  -H "X-API-Key: $ORBIT_API_KEY"

{
  "data": {
    "rows": [
      {
        "query_normalized": "rma:",
        "query_text_sample": "rma: RMA-1234",
        "count": 61,
        "surfaces": ["messages"],
        "last_seen_at": "2026-08-23T08:03:41.226Z"
      }
    ],
    "range": { "from": "2026-08-18T00:00:00.000Z", "to": "2026-08-25T23:59:59.999Z" }
  }
}

curl -X POST https://api.orbit.devotel.io/api/v1/search-analytics/click \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "searchAnalyticsId": "sa_…", "entityId": "contact_…" }'

{
  "data": { "recorded": true }
}

​

See also

• Search Analytics API reference — full endpoint shapes for the four read aggregations plus click attribution
• Insights dashboards guide — sibling operator walkthrough for the broader Insights console surfaces
• Search message history — the fielded DSL every per-surface search uses
• Error codes — VALIDATION_ERROR and the standard error envelope