> ## Documentation Index > Fetch the complete documentation index at: https://docs.usehindsight.com/llms.txt > Use this file to discover all available pages before exploring further. # Select Deal > Returns lean, paginated deal rows for triage. Use `get-deal` to retrieve the full details for returned deal IDs. Find analyzed deals using structured filters. This endpoint returns lean rows for triage; use [Get Deal](/api-reference/get-deal) with the returned `deal_id` values when you need summaries and competitor positioning. ``` POST https://app.usehindsight.com/api/v1/tools/select-deal ``` ## Request Body All fields are optional. `query`, `semantic_query`, and `segment_id` have compatibility constraints described below. | Field | Type | Description | | ---------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Fuzzy match against the deal or client name. Cannot be combined with `semantic_query` or `segment_id`. | | `semantic_query` | string | Search deal content by meaning, such as `deals lost over security compliance`. Returns a single ranked top-N result set and cannot be combined with `query` or `segment_id`. | | `segment_id` | string | Filter by a segment ID. Cannot be combined with `query`. | | `competitor_id` | string | Filter by competitor ID. | | `deal_stage` | string or string\[] | One or more stage names, such as `Closed Won`. | | `amount` | object | `{ "min": number, "max": number }`. | | `close_date` | object | `{ "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }`. | | `type` | string | Filter by deal type. | | `region` | string | Filter by region. | | `owner_name` | string | Owner name or email. Use `me`, `my`, or `mine` for the authenticated user's deals. | | `limit` | number | Results per page, from 1 to 50. Defaults to 20. | | `page` | number | One-indexed page number. Defaults to 1. | ## Response Each response contains a `results` array and paging metadata. A row is intentionally lean and includes identifiers and common deal attributes, not the full summary or competitor positioning. ```json theme={null} { "total_returned": 1, "limit_applied": 20, "page": 1, "page_size": 20, "has_more": false, "next_page": null, "results": [ { "type": "deal", "id": "deal_123", "deal_id": "deal_123", "name": "Acme Enterprise Renewal", "client_name": "Acme Corp", "stage": "Closed Lost", "amount": 50000, "close_date": "2026-06-30", "deal_type": "Renewal", "region": "North America", "primary_competitor": "Example Competitor", "url": "https://app.usehindsight.com/deals/deal_123/home" } ] } ``` When `has_more` is `true`, call the endpoint again with `page` set to `next_page`. Use `deal_id` from a result as input to [Get Deal](/api-reference/get-deal). ```bash cURL theme={null} curl -X POST https://app.usehindsight.com/api/v1/tools/select-deal \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "competitor_id": "comp_123", "deal_stage": ["Closed Won", "Closed Lost"], "close_date": { "from": "2026-01-01", "to": "2026-06-30" }, "limit": 20, "page": 1 }' ``` ## Limits and Errors Each successful, valid request consumes one read from the shared organization read bucket. See [Rate Limits](/integrations/api#rate-limits) for plan limits, returned headers, and retry guidance. Invalid input returns `400`; unauthorized or disallowed calls return `401` or `403` without consuming read usage. ## OpenAPI ````yaml POST /tools/select-deal openapi: 3.1.0 info: title: Hindsight API description: > Integrate Hindsight competitive intelligence, win-loss insights, and deal data into your applications. ## Authentication All API requests require a Bearer token in the Authorization header: ``` Authorization: Bearer YOUR_API_KEY ``` Get your API key from the [Hindsight dashboard](https://app.usehindsight.com/settings/keys). ## Rate Limits API and MCP requests are rate-limited per organization. The per-minute rate limit is shared across API and MCP traffic and uses a 60-second sliding window. Direct tool calls also consume a monthly usage bucket; `select-deal` and `get-deal` consume one read each from the shared reads bucket after authorization and validation succeed. | Plan | Per Minute | Per Month | |------|-----------|----------| | Essentials | 10 | 10,000 | | Growth | 60 | 30,000 | | Enterprise | 300 | 100,000 | Successful direct-tool responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix milliseconds), `X-Usage-Used`, `X-Usage-Limit`, `X-Usage-Remaining`, and `X-Usage-Period-End`. When a limit is exceeded, the API returns a `429` response with the relevant headers. version: 1.0.0 contact: name: Hindsight Support url: https://usehindsight.com/support email: support@hindsight.com servers: - url: https://app.usehindsight.com/api/v1 description: Production server security: - bearerAuth: [] tags: - name: Chat description: AI-powered chat completions with competitive intelligence - name: Deals description: Access and export deal data - name: Documents description: Upload and manage documents - name: Interviews description: Create and manage win-loss interview requests - name: Tools description: Structured Hindsight tool calls for application-controlled workflows paths: /tools/select-deal: post: tags: - Tools summary: Filter and list analyzed deals description: >- Returns lean, paginated deal rows for triage. Use `get-deal` to retrieve the full details for returned deal IDs. operationId: selectDeal requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SelectDealRequest' responses: '200': description: Matching deal rows content: application/json: schema: $ref: '#/components/schemas/SelectDealResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalServerError' components: schemas: SelectDealRequest: type: object properties: query: type: string nullable: true description: >- Fuzzy deal or client-name match. Cannot be used with semantic_query or segment_id. semantic_query: type: string nullable: true description: >- Conceptual search over deal content. Cannot be used with query or segment_id. segment_id: type: string nullable: true description: Segment ID. Cannot be used with query. competitor_id: type: string nullable: true deal_stage: oneOf: - type: string - type: array items: type: string nullable: true description: One or more deal-stage names. amount: type: object nullable: true properties: min: type: number nullable: true max: type: number nullable: true close_date: type: object nullable: true properties: from: type: string nullable: true to: type: string nullable: true type: type: string nullable: true region: type: string nullable: true owner_name: type: string nullable: true description: Owner name, email, or `me`, `my`, or `mine`. limit: type: integer minimum: 1 maximum: 50 default: 20 page: type: integer minimum: 1 default: 1 SelectDealResponse: type: object properties: total_returned: type: integer limit_applied: type: integer nullable: true page: type: integer page_size: type: integer has_more: type: boolean next_page: type: integer nullable: true results: type: array items: $ref: '#/components/schemas/DealToolRow' DealToolRow: type: object properties: type: type: string example: deal id: type: string nullable: true deal_id: type: string nullable: true name: type: string nullable: true client_name: type: string nullable: true stage: type: string nullable: true amount: type: number nullable: true close_date: type: string nullable: true url: type: string nullable: true Error: type: object properties: error: type: object properties: code: type: string description: Error code example: unauthorized message: type: string description: Human-readable error message example: Invalid API key details: type: object description: Additional error details additionalProperties: true responses: BadRequest: description: Bad request - invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: bad_request message: Invalid parameters details: missing_fields: - file_name Unauthorized: description: Unauthorized - invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Invalid API key Forbidden: description: Forbidden - the API key's role cannot use this tool content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: Your role does not have permission to use this tool. RateLimitExceeded: description: >- Too many requests - per-minute rate limit or monthly usage quota exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limit_exceeded message: >- Rate limit exceeded. Please retry after the reset time in the response headers. headers: X-RateLimit-Limit: schema: type: integer description: Requests allowed in the current 60-second window. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current 60-second window. X-RateLimit-Reset: schema: type: integer format: int64 description: Unix timestamp in milliseconds when the rate-limit window resets. X-Usage-Used: schema: type: integer description: Requests consumed from the applicable monthly bucket. X-Usage-Limit: schema: type: integer description: Monthly allowance for the applicable usage bucket. X-Usage-Remaining: schema: type: integer description: Requests remaining in the applicable monthly usage bucket. X-Usage-Period-End: schema: type: string format: date-time description: ISO timestamp when the monthly usage period resets. InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: An unexpected error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: API key from Hindsight dashboard ````