> ## 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 Interview Status & Transcript

> Returns the current status of an interview request and, once completed, its full transcript.

Poll this endpoint to check whether a contact has completed their interview.
When `status` is `"completed"`, the `transcript` field contains the full conversation content.


<Accordion title="Copy for AI context">
  ```text theme={null}
  GET https://app.usehindsight.com/api/v1/interviews/{id}
  Authorization: Bearer YOUR_API_KEY

  Path parameter:
    id: integer  — the interview_request_id returned from POST /interviews

  200 Response:
  {
    "interview_request_id": 4821,
    "contact_id": "contact_abc123",
    "deal_id": "deal_xyz789",
    "survey_url": "https://app.usehindsight.com/survey?token=tok_xyz",
    "status": "created" | "sent" | "completed",
    "objective": "string | null",
    "email_sent_at": "2026-05-15T10:00:00Z | null",
    "created_at": "2026-05-15T09:00:00Z",
    "transcript": {               // null unless status = "completed"
      "document_id": "doc_abc123",
      "content": "**Paige:** ...\n\n**Jane:** ...",
      "created_at": "2026-05-16T14:30:00Z"
    } | null
  }

  Rate limits: 60 req/min (Essentials), 300 req/min (Growth), 1,000 req/min (Enterprise)
  ```
</Accordion>

## Overview

Returns the current status of an interview request and, once completed, its full transcript.

Poll this endpoint to check whether a contact has responded. When `status` is `"completed"`, the `transcript.content` field contains the full conversation in markdown.

## Status Values

| Status      | Meaning                                                        |
| ----------- | -------------------------------------------------------------- |
| `created`   | Request exists but no outreach email has been sent yet.        |
| `sent`      | Email sent; waiting for the contact to complete the interview. |
| `completed` | Interview finished. `transcript` is populated.                 |

## Path Parameter

| Parameter | Type    | Description                                                                                |
| --------- | ------- | ------------------------------------------------------------------------------------------ |
| `id`      | integer | The `interview_request_id` returned when the interview was created via `POST /interviews`. |

## Response

| Field                  | Type           | Description                                          |
| ---------------------- | -------------- | ---------------------------------------------------- |
| `interview_request_id` | integer        | ID of the interview request.                         |
| `contact_id`           | string \| null | ID of the contact being interviewed.                 |
| `deal_id`              | string \| null | Associated deal ID, or null.                         |
| `survey_url`           | string \| null | Direct link to the survey for this contact.          |
| `status`               | string         | `created`, `sent`, or `completed`.                   |
| `objective`            | string \| null | Interview-specific goal, if set.                     |
| `email_sent_at`        | string \| null | ISO timestamp when the outreach email was sent.      |
| `created_at`           | string         | ISO timestamp when the request was created.          |
| `transcript`           | object \| null | Populated when `status` is `"completed"`. See below. |

### Transcript object

| Field         | Type   | Description                                                                                  |
| ------------- | ------ | -------------------------------------------------------------------------------------------- |
| `document_id` | string | ID of the document storing the transcript.                                                   |
| `content`     | string | Full interview conversation in markdown. Speaker turns are formatted as `**Name:** message`. |
| `created_at`  | string | ISO timestamp when the transcript was saved.                                                 |

## Polling

There is no webhook support yet — poll this endpoint to detect completion. A reasonable cadence for most use cases is every 5–15 minutes after sending.

```
POST /interviews         → store interview_request_id
GET  /interviews/{id}   → poll until status = "completed"
                        → read transcript.content
```

Avoid polling faster than once per minute — completions typically happen hours after the email is sent.

## Rate Limits

| Plan       | Requests per Minute |
| ---------- | ------------------- |
| Essentials | 60                  |
| Growth     | 300                 |
| Enterprise | 1,000               |

## Examples

<RequestExample>
  ```bash Check interview status theme={null}
  curl "https://app.usehindsight.com/api/v1/interviews/4821" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js - Poll until completed theme={null}
  const API_KEY = process.env.HINDSIGHT_API_KEY;

  async function waitForInterview(interviewRequestId, { intervalMs = 5 * 60 * 1000, maxAttempts = 48 } = {}) {
    for (let i = 0; i < maxAttempts; i++) {
      const res = await fetch(`https://app.usehindsight.com/api/v1/interviews/${interviewRequestId}`, {
        headers: { 'Authorization': `Bearer ${API_KEY}` },
      });
      const data = await res.json();

      if (data.status === 'completed') {
        return data.transcript;
      }

      console.log(`[${i + 1}/${maxAttempts}] Status: ${data.status} — checking again in ${intervalMs / 60000}m`);
      await new Promise((r) => setTimeout(r, intervalMs));
    }

    return null; // timed out
  }

  const transcript = await waitForInterview(4821);
  if (transcript) {
    console.log('Interview completed:', transcript.content);
  }
  ```

  ```python Python - Fetch transcript once ready theme={null}
  import requests
  import time

  API_KEY = 'your_api_key_here'

  def get_interview(interview_request_id):
      response = requests.get(
          f'https://app.usehindsight.com/api/v1/interviews/{interview_request_id}',
          headers={'Authorization': f'Bearer {API_KEY}'}
      )
      response.raise_for_status()
      return response.json()

  def wait_for_completion(interview_request_id, interval_seconds=300, max_attempts=48):
      for attempt in range(max_attempts):
          data = get_interview(interview_request_id)

          if data['status'] == 'completed':
              return data['transcript']

          print(f"[{attempt + 1}/{max_attempts}] Status: {data['status']}")
          time.sleep(interval_seconds)

      return None  # timed out

  transcript = wait_for_completion(4821)
  if transcript:
      print('Transcript:', transcript['content'])
  ```
</RequestExample>

## Error Responses

| Code                  | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `unauthorized`        | Invalid or missing API key.                                    |
| `not_found`           | Interview request not found, or it belongs to a different org. |
| `rate_limit_exceeded` | Too many requests. Check `X-RateLimit-Reset` and retry after.  |

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Interview request not found"
  }
}
```


## OpenAPI

````yaml GET /interviews/{id}
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 requests are rate-limited per plan:


    | Plan | Per Minute | Per Month |

    |------|-----------|----------|

    | Essentials | 10 | 10,000 |

    | Growth | 60 | 30,000 |

    | Enterprise | 300 | 100,000 |


    When a limit is exceeded, the API returns a `429` response. Check the
    `Retry-After` header for when to retry.
  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
paths:
  /interviews/{id}:
    get:
      tags:
        - Interviews
      summary: Get interview status and transcript
      description: >
        Returns the current status of an interview request and, once completed,
        its full transcript.


        Poll this endpoint to check whether a contact has completed their
        interview.

        When `status` is `"completed"`, the `transcript` field contains the full
        conversation content.
      operationId: getInterview
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          description: The `interview_request_id` returned when the interview was created.
          example: 4821
      responses:
        '200':
          description: Interview request found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInterviewResponse'
              examples:
                pending:
                  summary: Interview sent, awaiting response
                  value:
                    interview_request_id: 4821
                    contact_id: contact_abc123
                    deal_id: deal_xyz789
                    survey_url: https://app.usehindsight.com/survey?token=tok_xyz
                    status: sent
                    objective: Understand why we lost to Competitor X
                    email_sent_at: '2026-05-15T10:00:00Z'
                    created_at: '2026-05-15T09:00:00Z'
                    transcript: null
                completed:
                  summary: Interview completed
                  value:
                    interview_request_id: 4821
                    contact_id: contact_abc123
                    deal_id: deal_xyz789
                    survey_url: https://app.usehindsight.com/survey?token=tok_xyz
                    status: completed
                    objective: Understand why we lost to Competitor X
                    email_sent_at: '2026-05-15T10:00:00Z'
                    created_at: '2026-05-15T09:00:00Z'
                    transcript:
                      document_id: doc_abc123
                      content: |-
                        **Paige:** Thanks for taking the time today...

                        **Jane:** Happy to help...
                      created_at: '2026-05-16T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Interview request not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: not_found
                  message: Interview request not found
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    GetInterviewResponse:
      type: object
      properties:
        interview_request_id:
          type: integer
          description: ID of the interview request.
          example: 4821
        contact_id:
          type: string
          nullable: true
          description: ID of the contact being interviewed.
          example: contact_abc123
        deal_id:
          type: string
          nullable: true
          description: Associated deal ID, or null.
          example: deal_xyz789
        survey_url:
          type: string
          nullable: true
          description: Direct link to the survey for this contact.
          example: https://app.usehindsight.com/survey?token=tok_xyz
        status:
          type: string
          enum:
            - created
            - sent
            - completed
          description: |
            `created` — request exists, no email sent yet.
            `sent` — email sent, awaiting the contact's response.
            `completed` — interview finished; `transcript` is populated.
          example: sent
        objective:
          type: string
          nullable: true
          description: The interview-specific goal, if set.
          example: Understand why we lost to Competitor X
        email_sent_at:
          type: string
          format: date-time
          nullable: true
          description: ISO timestamp when the outreach email was sent, or null.
          example: '2026-05-15T10:00:00Z'
        created_at:
          type: string
          format: date-time
          description: ISO timestamp when the interview request was created.
          example: '2026-05-15T09:00:00Z'
        transcript:
          nullable: true
          description: Present when `status` is `"completed"`, null otherwise.
          type: object
          properties:
            document_id:
              type: string
              description: ID of the document storing the transcript.
              example: doc_abc123
            content:
              type: string
              description: Full interview transcript in markdown format.
              example: |-
                **Paige:** Thanks for taking the time today...

                **Jane:** Happy to help...
            created_at:
              type: string
              format: date-time
              description: ISO timestamp when the transcript was saved.
              example: '2026-05-16T14:30:00Z'
    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:
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid API key
    RateLimitExceeded:
      description: Too many requests - rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limit_exceeded
              message: >-
                Rate limit exceeded. Limits are 10/min on Essentials, 60/min on
                Growth, and 300/min on Enterprise. Check the Retry-After header.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Number of seconds to wait before retrying
    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

````