> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Search history > Keyword and semantic search over one customer history, with computed recurrence. ## OpenAPI ````yaml openapi/en/cell.json POST /v1/history/search openapi: 3.1.0 info: title: Niadra data API version: '1' description: >- Writing, context, history, objects, identity, privacy and governance of one space. Every space has a stable address, with the space and the region in its name. servers: - url: https://{space}.{region}.api.niadra.com variables: space: default: acme-prod description: The space, which comes in the source key. region: default: us-east-1 description: The region of the space, which also comes in the key. security: [] paths: /v1/history/search: post: tags: - read summary: Search history description: >- Keyword (BM25) and semantic search restricted to one profile, fused by rank. Covers episodes, facts, open items, system events, actions, objects and patterns. The `recurrence` block counts how many times the same category happened. Same policy, verification level and receipt as the context. p95 under 200 ms. **Authentication.** Source key: `Authorization: Bearer nia_sk_...`. Required scope: `search`. operationId: search_v1_history_search_post requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequest' example: subject: type: phone_e164 value: '+14155550123' query: credit for missed technician visit max_tokens: 300 verification: V1 conversation_id: call-4471 required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SearchResponse' example: items: - id: ep_01J2 kind: episode text: >- Technician did not show up · $40 credit on the April bill · settled at: '2026-03-12T14:20:00Z' channel: voice source_id: src_voice outcome: resolved confidence: 0.94 origin_event_id: evt_01J2A - id: ep_01J3 kind: episode text: Customer confirmed the credit and the new visit at: '2026-03-14T12:02:00Z' channel: whatsapp source_id: src_whatsapp outcome: resolved confidence: 0.91 origin_event_id: evt_01J3C recurrence: category: technician_visit occurrences: 2 window_days: 365 last_at: '2026-03-12T14:20:00Z' last_outcome: resolved last_resolution: $40 credit withheld: 0 as_of: '2026-09-22T17:07:02Z' tokens_used: 61 degraded: null description: Matching items, cut to `max_tokens` by value. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: The request does not match the contract. security: - sourceKey: [] x-codeSamples: - lang: python label: Python source: |- result = niadra.search( phone("+14155550123"), "credit for missed technician visit", max_tokens=300, conversation_id="call-4471", voice=True, ) if result.recurrence: print(result.recurrence.occurrences, result.recurrence.last_resolution) - lang: typescript label: TypeScript source: |- const { data } = await niadra.search({ subject: handles.phone("+14155550123"), query: "credit for missed technician visit", max_tokens: 300, conversation_id: "call-4471", }); if (data?.recurrence) { console.log(data.recurrence.occurrences, data.recurrence.last_resolution); } components: schemas: SearchRequest: additionalProperties: false properties: about: anyOf: - $ref: '#/components/schemas/Handle' - type: 'null' conversation_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Conversation Id filters: $ref: '#/components/schemas/HistoryFilters' max_tokens: default: 800 maximum: 4000 minimum: 50 title: Max Tokens type: integer description: >- Budget of the answer. Items are cut by value, never by arrival order. Use 300 for voice. query: maxLength: 2000 minLength: 1 title: Query type: string description: Natural language or keywords. subject: $ref: '#/components/schemas/Handle' task_id: anyOf: - maxLength: 512 minLength: 1 type: string - type: 'null' title: Task Id verification: $ref: '#/components/schemas/Verification' default: V0 required: - subject - query title: SearchRequest type: object SearchResponse: additionalProperties: false properties: as_of: anyOf: - format: date-time type: string - type: 'null' title: As Of degraded: anyOf: - type: string - type: 'null' description: '`text_only` when the encoder was unavailable.' title: Degraded items: items: $ref: '#/components/schemas/HistoryItem' title: Items type: array recurrence: anyOf: - $ref: '#/components/schemas/Recurrence' - type: 'null' tokens_used: title: Tokens Used type: integer withheld: default: 0 title: Withheld type: integer required: - items - tokens_used title: SearchResponse type: object Problem: additionalProperties: false description: RFC 9457 problem details; `code` comes from the versioned error catalog. properties: code: title: Code type: string detail: anyOf: - type: string - type: 'null' default: null title: Detail request_id: anyOf: - type: string - type: 'null' default: null title: Request Id status: title: Status type: integer title: title: Title type: string type: default: about:blank title: Type type: string required: - title - status - code title: Problem type: object Handle: additionalProperties: false description: >- An identifier of a subject in some channel or system: a phone, an e-mail, a CRM id. properties: scope: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: >- Namespace for scoped identifiers: the WhatsApp Business account for `wa_bsuid`, the system for `system_id`, the country for `gov_id_hmac`. title: Scope subject_kind: anyOf: - $ref: '#/components/schemas/SubjectKind' - type: 'null' description: Defaults to `person`, except for organization-only handle types. type: $ref: '#/components/schemas/HandleType' value: maxLength: 320 minLength: 1 title: Value type: string description: >- The identifier. Normalized on the server: E.164 for phones, lowercase for e-mail. required: - type - value title: Handle type: object HistoryFilters: additionalProperties: false properties: categories: items: maxLength: 256 minLength: 1 type: string title: Categories type: array channels: items: maxLength: 256 minLength: 1 type: string title: Channels type: array item_kinds: items: enum: - episode - fact - open_item - action - system_event - object - trait type: string title: Item Kinds type: array object: anyOf: - $ref: '#/components/schemas/ObjectRef' - type: 'null' outcome: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' title: Outcome since: anyOf: - format: date-time type: string - type: 'null' title: Since until: anyOf: - format: date-time type: string - type: 'null' title: Until title: HistoryFilters type: object Verification: description: Session verification levels. `no_customer` sits outside the V0-V4 scale. enum: - V0 - V1 - V2 - V3 - V4 - no_customer title: Verification type: string HistoryItem: additionalProperties: false properties: at: format: date-time title: At type: string channel: anyOf: - type: string - type: 'null' title: Channel confidence: anyOf: - type: number - type: 'null' title: Confidence id: title: Id type: string kind: title: Kind type: string description: >- One of `episode`, `fact`, `open_item`, `action`, `system_event`, `object`, `trait`. origin_event_id: anyOf: - type: string - type: 'null' title: Origin Event Id description: The event this item came from. outcome: anyOf: - type: string - type: 'null' title: Outcome source_id: anyOf: - type: string - type: 'null' title: Source Id text: title: Text type: string description: Dense text, in the same key-value style as the pack. required: - id - kind - text - at title: HistoryItem type: object Recurrence: additionalProperties: false properties: category: title: Category type: string last_at: anyOf: - format: date-time type: string - type: 'null' title: Last At last_outcome: anyOf: - type: string - type: 'null' title: Last Outcome last_resolution: anyOf: - type: string - type: 'null' title: Last Resolution occurrences: title: Occurrences type: integer window_days: title: Window Days type: integer required: - category - occurrences - window_days title: Recurrence type: object description: >- How many times this happened, counted over typed episodes. A count, not a guess. SubjectKind: enum: - person - account - partner title: SubjectKind type: string description: >- A person, a customer organization (`account`) or an organization that takes part without being a customer (`partner`). HandleType: enum: - phone_e164 - wa_id - wa_jid - wa_lid - wa_bsuid - email - gov_id_hmac - app_user_id - system_id - org_registry_hmac - email_domain - anon_id title: HandleType type: string description: >- The kind of identifier. The value is classified by its format, never by the field it came from. ObjectRef: additionalProperties: false description: >- A business object in a system of record, e.g. `invoice` / `erp` / `0823`. properties: id: maxLength: 512 minLength: 1 title: Id type: string description: The id in that system. namespace: maxLength: 256 minLength: 1 title: Namespace type: string description: The system it lives in, such as `erp`. type: maxLength: 256 minLength: 1 title: Type type: string description: Object type, such as `invoice`, `order` or `ticket`. required: - type - namespace - id title: ObjectRef type: object securitySchemes: sourceKey: type: http scheme: bearer description: nia_sk_... ````