> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jobhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Interviews

Retrieves a paginated list of interviews for your account. Supports filtering by status, date range, candidate email, and position.

## Query Parameters

<ParamField query="cursor" type="string">
  Pagination cursor for retrieving next page of results
</ParamField>

<ParamField query="limit" type="integer" default="25">
  Number of interviews to return per page (1-100)
</ParamField>

<ParamField query="status" type="string">
  Filter by interview status

  <Expandable title="Status values">
    * `scheduled`: Interview is scheduled but not started
    * `in_progress`: Interview is currently active
    * `completed`: Interview has finished
    * `cancelled`: Interview was cancelled
  </Expandable>
</ParamField>

<ParamField query="candidate_email" type="string">
  Filter by candidate email address
</ParamField>

<ParamField query="position" type="string">
  Filter by job position or role
</ParamField>

<ParamField query="created_after" type="string">
  ISO 8601 timestamp to filter interviews created after this date
</ParamField>

<ParamField query="created_before" type="string">
  ISO 8601 timestamp to filter interviews created before this date
</ParamField>

<ParamField query="scheduled_after" type="string">
  ISO 8601 timestamp to filter interviews scheduled after this date
</ParamField>

<ParamField query="scheduled_before" type="string">
  ISO 8601 timestamp to filter interviews scheduled before this date
</ParamField>

<ParamField query="include_results" type="boolean" default="false">
  Include basic result scores in the response (for completed interviews)
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of interview objects

  <Expandable title="Interview object">
    <ResponseField name="id" type="string">
      Unique interview identifier
    </ResponseField>

    <ResponseField name="status" type="string">
      Current interview status
    </ResponseField>

    <ResponseField name="candidate_email" type="string">
      Candidate's email address
    </ResponseField>

    <ResponseField name="position" type="string">
      Job position for the interview
    </ResponseField>

    <ResponseField name="skills" type="array">
      Array of skills being assessed
    </ResponseField>

    <ResponseField name="scheduled_at" type="string">
      ISO 8601 timestamp when interview is scheduled
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp when interview was created
    </ResponseField>

    <ResponseField name="results" type="object">
      Basic results (when include\_results=true and status=completed)

      <Expandable title="Results object">
        <ResponseField name="overall_score" type="number">
          Overall interview score (0-100)
        </ResponseField>

        <ResponseField name="recommendation" type="string">
          AI recommendation: `hire`, `maybe`, `no_hire`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information

  <Expandable title="Pagination object">
    <ResponseField name="next_cursor" type="string">
      Cursor for next page (null if no more pages)
    </ResponseField>

    <ResponseField name="has_more" type="boolean">
      Whether there are more results available
    </ResponseField>

    <ResponseField name="total_count" type="integer">
      Total number of interviews matching filters
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://backend.jobhive.ai/v1/interviews" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL with Filters theme={null}
  curl -X GET "https://backend.jobhive.ai/v1/interviews?status=completed&limit=50&include_results=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL with Date Range theme={null}
  curl -X GET "https://backend.jobhive.ai/v1/interviews?created_after=2024-01-01T00:00:00Z&created_before=2024-01-31T23:59:59Z" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  // Get all completed interviews
  const completedInterviews = await jobhive.interviews.list({
    status: 'completed',
    include_results: true,
    limit: 100
  });

  console.log(`Found ${completedInterviews.pagination.total_count} completed interviews`);

  // Paginate through all results
  let cursor = null;
  const allInterviews = [];

  do {
    const response = await jobhive.interviews.list({
      cursor,
      limit: 100
    });
    
    allInterviews.push(...response.data);
    cursor = response.pagination.next_cursor;
  } while (cursor);

  console.log(`Total interviews: ${allInterviews.length}`);
  ```

  ```python Python theme={null}
  # Get interviews from last 30 days
  from datetime import datetime, timedelta

  thirty_days_ago = (datetime.now() - timedelta(days=30)).isoformat()

  recent_interviews = client.interviews.list(
      created_after=thirty_days_ago,
      include_results=True,
      limit=100
  )

  print(f"Found {recent_interviews.pagination.total_count} recent interviews")

  # Filter by position and status
  frontend_interviews = client.interviews.list(
      position="Frontend Developer",
      status="completed",
      include_results=True
  )

  for interview in frontend_interviews.data:
      print(f"Candidate: {interview.candidate_email}, Score: {interview.results.overall_score}")
  ```
</RequestExample>

<ResponseExample>
  ```json Basic Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "int_abc123def456",
        "status": "completed",
        "candidate_email": "john.doe@example.com",
        "position": "Full Stack Developer",
        "skills": ["JavaScript", "React", "Node.js"],
        "scheduled_at": "2024-01-15T15:30:00Z",
        "created_at": "2024-01-15T14:30:00Z"
      },
      {
        "id": "int_def456ghi789",
        "status": "scheduled",
        "candidate_email": "jane.smith@example.com",
        "position": "Frontend Developer",
        "skills": ["React", "TypeScript", "CSS"],
        "scheduled_at": "2024-01-16T10:00:00Z",
        "created_at": "2024-01-15T16:45:00Z"
      }
    ],
    "pagination": {
      "next_cursor": "eyJpZCI6ImludF9kZWY0NTZnaGk3ODkifQ==",
      "has_more": true,
      "total_count": 156
    },
    "meta": {
      "timestamp": "2024-01-15T20:30:00Z",
      "request_id": "req_list_int_001"
    }
  }
  ```

  ```json Response with Results theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "int_abc123def456",
        "status": "completed",
        "candidate_email": "john.doe@example.com",
        "position": "Full Stack Developer",
        "skills": ["JavaScript", "React", "Node.js"],
        "scheduled_at": "2024-01-15T15:30:00Z",
        "created_at": "2024-01-15T14:30:00Z",
        "results": {
          "overall_score": 78,
          "recommendation": "hire"
        }
      },
      {
        "id": "int_ghi789jkl012",
        "status": "completed",
        "candidate_email": "bob.wilson@example.com",
        "position": "Backend Developer",
        "skills": ["Python", "Django", "PostgreSQL"],
        "scheduled_at": "2024-01-14T14:00:00Z",
        "created_at": "2024-01-14T10:15:00Z",
        "results": {
          "overall_score": 65,
          "recommendation": "maybe"
        }
      }
    ],
    "pagination": {
      "next_cursor": null,
      "has_more": false,
      "total_count": 2
    }
  }
  ```
</ResponseExample>

## Common Use Cases

### Generate Hiring Reports

```javascript theme={null}
async function generateHiringReport(startDate, endDate) {
  const interviews = await jobhive.interviews.list({
    created_after: startDate,
    created_before: endDate,
    status: 'completed',
    include_results: true,
    limit: 100
  });
  
  const stats = {
    total: interviews.data.length,
    hired: interviews.data.filter(i => i.results.recommendation === 'hire').length,
    maybe: interviews.data.filter(i => i.results.recommendation === 'maybe').length,
    rejected: interviews.data.filter(i => i.results.recommendation === 'no_hire').length,
    averageScore: interviews.data.reduce((sum, i) => sum + i.results.overall_score, 0) / interviews.data.length
  };
  
  return stats;
}
```

### Monitor Interview Pipeline

```python theme={null}
def get_pipeline_status():
    pipeline = {
        'scheduled': client.interviews.list(status='scheduled').pagination.total_count,
        'in_progress': client.interviews.list(status='in_progress').pagination.total_count,
        'completed_today': len([
            i for i in client.interviews.list(
                status='completed',
                created_after=datetime.now().date().isoformat()
            ).data
        ])
    }
    
    return pipeline
```

### Find Top Performers

```javascript theme={null}
async function findTopPerformers(position, minScore = 80) {
  const interviews = await jobhive.interviews.list({
    position,
    status: 'completed',
    include_results: true,
    limit: 100
  });
  
  return interviews.data
    .filter(interview => interview.results.overall_score >= minScore)
    .sort((a, b) => b.results.overall_score - a.results.overall_score)
    .map(interview => ({
      candidate: interview.candidate_email,
      score: interview.results.overall_score,
      date: interview.scheduled_at
    }));
}
```

<Note>
  Use pagination for large result sets. The API returns a maximum of 100 interviews per request.
</Note>

<Tip>
  Combine multiple filters to create specific reports. For example, filter by position and date range to analyze hiring trends for specific roles.
</Tip>