Open in documentation hub (sidebar) · 中文

Facet aggregation

Query a facet and return hit counts for facet values—commonly used for filters and aggregation UIs.

API overview

Method POST
Path /1/indexes/{indexName}/facets/{facetName}/query
Base URL example https://api.prophetes.ai
Full URL example https://api.prophetes.ai/1/indexes/{indexName}/facets/{facetName}/query

Demo Download

Download our official Demos to quickly integrate Insight Search into your application:

Python Demo
Uses standard library urllib with no additional dependencies
Download Demo
Java Demo
Uses java.net.http.HttpClient with no third-party dependencies
Download Demo

Authentication

Header Description
x-insight-application-id Application ID
x-insight-api-key API Key
Content-Type application/json

Request body format

JSON body with optional params, facetQuery, and maxFacetHits. 

{
  "params": "hitsPerPage=2&getRankingInfo=1",
  "facetQuery": "",
  "maxFacetHits": 15
}

Request parameters

Parameter Type Required Default Description
params string No "" Pagination and controls as a query string
facetQuery string No "" Empty returns all facet values; non-empty filters to matching facet values
maxFacetHits integer No 15 Maximum number of facet hits to return

Response structure

{
  "facetHits": [
    { "count": 5, "highlighted": "Bathroom <em>Furniture</em>", "value": "Bathroom Furniture" }
  ],
  "exhaustiveFacetsCount": true,
  "processingTimeMS": 44
}

Example

curl -X POST "https://api.prophetes.ai/1/indexes/INSIGHT_INDEX_NAME/facets/INSIGHT_FACET_NAME/query" \
  -H "Content-Type: application/json" \
  -H "x-insight-api-key: INSIGHT_API_KEY" \
  -H "x-insight-application-id: INSIGHT_APPLICATION_ID" \
  -d '{"facetQuery":"Furniture","maxFacetHits":15,"params":"hitsPerPage=2&getRankingInfo=1"}'