Find Similar Records

import json
import requests
BASE_URL = "https://acme.captain.dev"
API_KEY = "your_search_key"
INDEX = "products"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}
response = requests.post(
    f"{BASE_URL}/v1/indexes/{INDEX}/similar",
    headers=headers,
    json={
        "id": "sku-10482",
        "k": 2,
    },
    timeout=30.0,
)
print(json.dumps(response.json(), indent=2))

{
  "hits": [
    {
      "id": "sku-11020",
      "title": "Targhee III Waterproof Mid Boot",
      "brand": "KEEN",
      "category": "Hiking Boots",
      "price": 150,
      "rating": 4.4,
      "image_url": "https://cdn.acme.example/img/sku-11020.jpg",
      "score": 0.884
    },
    {
      "id": "sku-10517",
      "title": "X Ultra 4 Mid GTX Hiking Boot",
      "brand": "Salomon",
      "category": "Hiking Boots",
      "price": 165,
      "rating": 4.5,
      "image_url": "https://cdn.acme.example/img/sku-10517.jpg",
      "score": 0.861
    }
  ],
  "total": 2,
  "timing": {
    "engine_ms": 5.8
  }
}

Find records similar to one record in the same index.

Authentication

AuthorizationBearer

A search key, issued by Captain. Sent as Authorization: Bearer <key>.

AuthorizationBearer

A scoped key for one end user, minted from an issuer key that Captain issues. Sent as Authorization: Bearer <key>.

Path parameters

indexstringRequiredformat: "^[a-z0-9][a-z0-9_-]{0,47}$"

index name

Request

This endpoint expects an object.

idstringRequired

kintegerOptional<=50Defaults to 10

filterstringOptional

fieldsboolean or list of stringsOptional

Response headers

X-Captain-Applied-Seqinteger

the last update seq search had applied when this request started; the answer reflects at least that much (GET …/updates applied_seq). Not on 401 or 403, nor for an index this server does not have

X-Captain-Index-IncarnationstringOptional

the index’s incarnation, an opaque string: it changes only when the index is deleted and created again (whose seqs start again at 1), or restored from a backup (whose seqs continue from the backup’s). Sent with X-Captain-Applied-Seq

Response

results

hitslist of objectsOptional

totalintegerOptional

search: the number of candidates the search ranked (an estimate, not a count of every match) unless the search asked exact_total, when it is the number the Algolia host answers as nbHits (see total_basis). Page with page.has_more, not total. Browse: every record the filter keeps. With group_by too: records, not groups

total_exactbooleanOptional

true when total is an exact number (search with exact_total: total_basis pageable or all_matches). False: an estimate (candidates) or the 1,000 floor (paging_limit)

total_basisenumOptional

what total is: pageable (exact: the hits the search can page through, under 1,000), all_matches (exact: every record that contains every query word, 1,000 or more), paging_limit (1,000, a floor: more may match), candidates (exact_total not asked, or type-ahead), or why an asked-for exact count fell back: busy, time_budget, error, no_required_words (no query word is required, so every record would match)

facet_detailmap from strings to objectsOptional

per facet in facets: basis all_matches (counted over every match, exact true) or relevant_results (counted over the relevance-cut set, exact false, with the reason when an asked-for exact count fell back)

groupedobjectOptional

present when results are grouped: the ranking, collapsed by the field’s value. A grouped search reads the 100 most relevant records, and further down the top 1,000 when k x size x 4 needs more; depth says how many it read

facetsmap from strings to lists of objectsOptional

facets_exactbooleanOptional

true only when every facet was counted over every matching record (browse). Search counts facets over the relevance-cut set (the most relevant results, up to 2,000): false

facet_set_sizeintegerOptional

query_idstringOptional

assignmentobjectOptional

only on a search of a catalog with an assignment that sent a user_token: the shopper’s group, and the index that served it

analyticsbooleanOptional

false when the request sent analytics: false (not logged, no query_id); absent otherwise

query_understandingobjectOptional

what the engine understood. Keys appear only when they apply; keys not listed here are diagnostics and may change

user_datalist of objectsOptional

the userData of each rule applied to this search, in rule order (at most 10). Absent when no applied rule has any

facet_orderingobjectOptional

how a page orders facets and their values (Algolia renderingContent.facetOrdering, snake_case). Returned on search and browse when the index or an applied rule sets one; the client orders with it

redirectobjectOptional

an applied rule’s redirect (the first in rule order): the page to send the shopper to instead of showing these results. Absent when no applied rule redirects

constraints_removedintegerOptional

constraints: strict: hits removed because a parsed quantity failed. hits [] with this > 0 means nothing meets the query’s quantities

sortobjectOptional

search with sort: which field and over what set

pageobjectOptional

search with page or per_page

facet_queryobjectOptional

facet_statsmap from strings to objectsOptional

requestobjectOptional

What ran. mode is full for Search Records and instant for Search As You Type, which skips the slower ranking steps to answer each keystroke. build is the index build that answered.

timingobjectOptional