> ## 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. # Get Deal > Retrieves the summary and per-competitor positioning for one to ten deal IDs. Get full details for one or more known deals. Use [Select Deal](/api-reference/select-deal) first when you need to find the relevant IDs. ``` POST https://app.usehindsight.com/api/v1/tools/get-deal ``` ## Request Body | Field | Type | Required | Description | | ---------- | --------- | -------- | ----------------------------------------------------------------------------------------------------- | | `deal_ids` | string\[] | Yes | One to ten deal IDs returned by `select-deal` or another Hindsight search. Duplicate IDs are ignored. | ```json theme={null} { "deal_ids": ["deal_123", "deal_456"] } ``` ## Response The response includes the same identifying fields as `select-deal`, plus the deal summary and per-competitor positioning. ```json theme={null} { "total_returned": 1, "limit_applied": null, "results": [ { "type": "deal", "id": "deal_123", "deal_id": "deal_123", "name": "Acme Enterprise Renewal", "client_name": "Acme Corp", "stage": "Closed Lost", "summary": "Acme selected the incumbent after raising pricing and implementation concerns.", "competitors": [ { "name": "Example Competitor", "positioning_summary": "Positioned as the lower-risk incumbent.", "key_differentiators": "Existing integration and implementation support" } ], "url": "https://app.usehindsight.com/deals/deal_123/home" } ] } ``` If a requested ID is not accessible to the authenticated organization or does not exist, it is omitted from `results`. ```bash cURL theme={null} curl -X POST https://app.usehindsight.com/api/v1/tools/get-deal \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "deal_ids": ["deal_123"] }' ``` ## 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. A request with no IDs or more than ten IDs returns `400` and does not consume read usage. ## OpenAPI ````yaml POST /tools/get-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/get-deal: post: tags: - Tools summary: Get full details for known deal IDs description: >- Retrieves the summary and per-competitor positioning for one to ten deal IDs. operationId: getDeal requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GetDealRequest' responses: '200': description: Detailed deal records content: application/json: schema: $ref: '#/components/schemas/GetDealResponse' '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: GetDealRequest: type: object required: - deal_ids properties: deal_ids: type: array minItems: 1 maxItems: 10 items: type: string GetDealResponse: type: object properties: total_returned: type: integer limit_applied: type: integer nullable: true results: type: array items: allOf: - $ref: '#/components/schemas/DealToolRow' - type: object properties: summary: type: string nullable: true competitors: type: array items: type: object properties: name: type: string nullable: true positioning_summary: type: string nullable: true key_differentiators: type: string nullable: true 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 ````