Select Deal

POST

tools

select-deal

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
  }'

{
  "total_returned": 123,
  "limit_applied": 123,
  "page": 123,
  "page_size": 123,
  "has_more": true,
  "next_page": 123,
  "results": [
    {
      "type": "deal",
      "id": "<string>",
      "deal_id": "<string>",
      "name": "<string>",
      "client_name": "<string>",
      "stage": "<string>",
      "amount": 123,
      "close_date": "<string>",
      "url": "<string>"
    }
  ]
}

{
  "error": {
    "code": "bad_request",
    "message": "Invalid parameters",
    "details": {
      "missing_fields": [
        "file_name"
      ]
    }
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Your role does not have permission to use this tool."
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after the reset time in the response headers."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}

Find analyzed deals using structured filters. This endpoint returns lean rows for triage; use 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.

{
  "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.

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 for plan limits, returned headers, and retry guidance. Invalid input returns 400; unauthorized or disallowed calls return 401 or 403 without consuming read usage.

Authorizations

Authorization

string

header

required

API key from Hindsight dashboard

Body

application/json

query

string | null

Fuzzy deal or client-name match. Cannot be used with semantic_query or segment_id.

semantic_query

string | null

Conceptual search over deal content. Cannot be used with query or segment_id.

segment_id

string | null

Segment ID. Cannot be used with query.

competitor_id

string | null

deal_stage

One or more deal-stage names.

amount

object | null

Show child attributes

close_date

object | null

Show child attributes

type

string | null

region

string | null

owner_name

string | null

Owner name, email, or me, my, or mine.

limit

integer

default:20

Required range: 1 <= x <= 50

page

integer

default:1

Required range: x >= 1

Response

Matching deal rows

total_returned

integer

limit_applied

integer | null

page

integer

page_size

integer

has_more

boolean

next_page

integer | null

results

object[]

Show child attributes

Get DealRetrieves the summary and per-competitor positioning for one to ten deal IDs.

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
  }'

{
  "total_returned": 123,
  "limit_applied": 123,
  "page": 123,
  "page_size": 123,
  "has_more": true,
  "next_page": 123,
  "results": [
    {
      "type": "deal",
      "id": "<string>",
      "deal_id": "<string>",
      "name": "<string>",
      "client_name": "<string>",
      "stage": "<string>",
      "amount": 123,
      "close_date": "<string>",
      "url": "<string>"
    }
  ]
}

{
  "error": {
    "code": "bad_request",
    "message": "Invalid parameters",
    "details": {
      "missing_fields": [
        "file_name"
      ]
    }
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Your role does not have permission to use this tool."
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after the reset time in the response headers."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}

Overview

Get Started

MCP

REST API

Integrations

Release Notes

Request Body

Response

Limits and Errors

Authorizations

Body

Response

​Request Body

​Response

​Limits and Errors

Authorizations

Body

Response

Request Body

Response

Limits and Errors