---
title: "Reasoning Search"
method: POST
path: "/search/reasoning"
tags: ["search"]
---

# Reasoning Search

`POST /search/reasoning`

## Request

- Base URL: `https://api.dataforb2b.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.dataforb2b.ai/search/reasoning`
- Auth: none declared

Agentic reasoning search over people.

**Authentication:** header `api_key: <your_api_key>`

**How it works:** a Claude agent reasons about the query, asks clarifying
questions when needed, probes the database in real time (free counts), then
runs the best final search. Multi-turn via `session_id`.

**Flow:**
1. First call: send `query`. Response is either `needs_input` (answer the
   questions) or `complete` (final results).
2. If `needs_input`: send back `session_id` + `answers` ({question_id: answer}).

**Pricing:** a flat agent fee (2 credits) per completed search, plus the final
search billed like `/search/people` (per-result, DB rate).
Clarification turns (`needs_input`) are free.

## Headers

- `api-key` string, nullable

## Request body

- ReasoningSearchRequest: Requête de recherche par raisonnement (agent multi-tour).
  - `query` string, nullable: Requête en langage naturel (max 3000 caractères). Obligatoire au 1er tour (session_id absent).
  - `session_id` string, nullable: Identifiant de session renvoyé par un tour 'needs_input'. À fournir avec 'answers'.
  - `answers` object, nullable: Réponses aux questions du tour précédent, au format {question_id: réponse}.
  - `category` 'people' | 'companies': Cible de recherche: 'people' ou 'companies'.
  - `max_results` integer: Nombre de résultats de la recherche finale.

## Response `200`

Successful Response

- ReasoningSearchResponse: Réponse du reasoning search : clarification en attente OU résultats finaux.
  - `status` 'needs_input' | 'complete', required: 'needs_input' = répondre aux questions ; 'complete' = résultats finaux.
  - `session_id` string, required: À renvoyer pour poursuivre la conversation.
  - `reasoning` string, nullable: Résumé du raisonnement / de ce qui a été recherché.
  - `questions` ReasoningQuestion[], nullable: Questions à poser à l'utilisateur.
    - `id` string, required
    - `text` string, required
    - `suggestions` string[], nullable
  - `applied_filters` object, nullable: FilterGroup final construit par l'agent et exécuté.
  - `total` integer, nullable
  - `count` integer, nullable
  - `has_next_page` boolean, nullable
  - `credits_used` number, nullable
  - `results` object[], nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/dataforb2b/apis/dataforb2b-api.md) · [All operations](https://skmtc.dev/dataforb2b/apis/dataforb2b-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dataforb2b/apis/dataforb2b-api/revisions/24ea79caa1a1?raw)