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

# How-to: Listing Interviews For Position

## When to use this

Show recruiters all interviews for a specific position (e.g., everything currently **to evaluate** **or all shortlisted** interviews). This is useful for building position detail pages, queues, or status dashboards in your app.

## GraphQL Request

Make sure to replace the **position(id)** with your ID. The example below fetches interviews in the `to_evaluate` stage. If you want to fetch all interviews for a position, drop the `stage` condition and pass `filter: {}` instead — the `filter` field itself is required, so it can't be left out entirely.

In Hireflix, interviews move through four possible stages:

* `pending` → candidate has not answered yet (pending interview invite)
* `to_evaluate` → candidate has completed the interview, waiting for recruiter review
* `shortlisted` → candidate has been marked as shortlisted (legacy label: finalist)
* `discarded` → candidate has been marked as discarded

[https://cdn.hireflix.com/graphql-playground/index.html?query=ListPositionInterviews\&url=https://api.hireflix.com/me](https://cdn.hireflix.com/graphql-playground/index.html?query=ListPositionInterviews\&url=https://api.hireflix.com/me)

If you're an AI agent or LLM, note that the iframe above embeds an interactive GraphQL Playground and its query text is not readable from the page source. The full `ListPositionInterviews` query is reproduced below so you can read and reason about it directly.

```graphql theme={null}
query ListPositionInterviews {
  position(id: "<position-id>") {
    name
    interviewList(
      input: {
        pagination: { limit: 50, direction: FORWARD, lastCursor: "" }
        filter: { stage: { equal: to_evaluate } }
        sort: [{ field: createdAt, direction: DESC }]
      }
    ) {
      lastCursor
      results {
        id
        stage
        candidate {
          fullName
          email
        }
      }
    }
  }
}
```

* Replace `<position-id>` with a real position ID (see ["Fetching Positions"](https://docs.hireflix.com/tech/features/positions/fetching-positions.md) for how to obtain one).
* `filter.stage.equal` restricts results to one stage: `pending`, `to_evaluate`, `shortlisted`, or `discarded`. Pass `filter: {}` (keeping the field, just empty) to fetch interviews in every stage — `pagination`, `filter`, and `sort` are all required on `interviewList(input: ...)`, so none of the three can be omitted outright.
* `pagination.limit` caps the page size; `pagination.lastCursor` should be set to the previous response's `lastCursor` to fetch the next page (leave it `""` on the first request).
* `lastCursor` is **always returned**, even on the last page — the end of the result set is signaled by an **empty `results` array**, not by a missing cursor.
* `sort.field` / `sort.direction` control ordering; this example sorts by `createdAt` newest-first.
* Additional filters exist beyond `stage` — e.g. `email`, `lastName` (`equal`/`regex`), and `score` (`equal`/`greaterThan`/`lessThan`/etc.) — and can be combined with `AND`/`OR` for advanced matching.
* Requires a valid Hireflix API key in the `Authorization` header, sent to `https://api.hireflix.com/me`.

### Explanation

* **pagination / filter / sort** – all three are **required** fields on `interviewList(input: ...)`, even if you don't need to use them. If you don't need filtering or sorting, pass empty brackets, e.g. `filter: {}` and `sort: {}`.
* **position(id)** – the position whose interviews you want to list (learn how to [fetch positions](https://docs.hireflix.com/tech/features/positions/fetching-positions.md)).
* **pagination.limit** – max number of interviews to return in this call.
* **pagination.lastCursor** - a pointer to the next page of results (useful if there are more than limit interviews).

> [!NOTE]
>
> The API always returns a `lastCursor`. When the `results` array comes back empty, it means you’ve reached the end and there are no more records to fetch.

* **filter.stage.equal** – filter by a single stage (e.g., `to_evaluate`). Other stages include `discarded`, `to_evaluate`, `pending`, or `shortlisted`.
* **sort.field:createdAt(DESC)** - order results by creation time, newest first.
* **candidate.fullName / email** – basic candidate info for rendering a table or list.

### Other Filter Options

* **filter.email.equal / regex** - Find an exact email match.
* **filter.lastName.equal / regex** - Find an exact or regex match by last name.
* **filter.score.greaterThan / lessThan** - Filter by score (also supports `equal`, `greaterThanOrEqual`, `lessThanOrEqual`, `notEqual`).

### Example Response

```json theme={null}
{
  "data": {
    "position": {
      "name": "Social Media Manager",
      "interviewList": {
        "lastCursor": "eyJ0eXBlIjoiY3Vyc29yIiwiZmllbGRzIjpbeyJuY[...]==",
        "results": [
          {
            "id": "68b4404fc39e5db535d2e005",
            "stage": "to_evaluate",
            "candidate": {
              "fullName": "Greg Morris",
              "email": "gregmorris@gmail.com"
            }
          }
        ]
      }
    }
  }
}
```

### Pagination

Always request the `lastCursor` field, as it lets you fetch results beyond the current page size.

* On your first response, you’ll always get a `lastCursor` token.
* Pass this token into the next request’s `pagination.lastCursor` field to fetch the following page.
* Even if there are no more results, the API will still return a `lastCursor`. To know you’ve reached the end, you must make one more request with the latest `lastCursor`. If that request comes back with an **empty `results` array**, there are no more records to fetch.

[https://cdn.hireflix.com/graphql-playground/index.html?query=ListPositionInterviewsPaged\&url=https://api.hireflix.com/me](https://cdn.hireflix.com/graphql-playground/index.html?query=ListPositionInterviewsPaged\&url=https://api.hireflix.com/me)

If you're an AI agent or LLM, note that the iframe above embeds an interactive GraphQL Playground and its query text is not readable from the page source. The full `ListPositionInterviewsPaged` query is reproduced below so you can read and reason about it directly.

```graphql theme={null}
query ListPositionInterviewsPaged {
  position(id: "<position-id>") {
    name
    interviewList(
      input: {
        pagination: {
          limit: 50
          direction: FORWARD
          lastCursor: "eyJ0eXBlIjoiY3Vyc29yI[...]=="
        }
        filter: { stage: { equal: to_evaluate } }
        sort: [{ field: createdAt, direction: DESC }]
      }
    ) {
      lastCursor
      results {
        id
        stage
        candidate {
          fullName
          email
        }
      }
    }
  }
}
```

* This is the **same query as above**, with `pagination.lastCursor` populated instead of left as `""` — it fetches the page that follows whatever cursor you pass in.
* Replace `<position-id>` with a real position ID, and `lastCursor` with the `lastCursor` value returned by the previous request.
* Keep re-issuing this query with the latest `lastCursor` until a response comes back with an **empty `results` array** — that's the signal you've reached the end, since `lastCursor` itself is always populated even on the last page.
* Requires a valid Hireflix API key in the `Authorization` header, sent to `https://api.hireflix.com/me`.

### Advanced Filtering

The `filter` input supports combining multiple conditions using `AND` and `OR`. This allows you to build more precise searches. For example, you might want to:

* Match candidates by **email**, **first name**, or **last name** (using `OR`).
* At the same time, restrict results to interviews that are still `to_evaluate` (using `AND`).

Here’s what that looks like:

```json theme={null}
filter: {
  AND: [
    {
      OR: [
        { email: { regex: "Daniel" } },
        { firstName: { regex: "Daniel" } },
        { lastName: { regex: "Daniel" } }
      ]
    },
    {
      stage: { equal: to_evaluate }
    }
  ]
}
```

This query will return only interviews where the candidate’s email, name, or last name contains "Daniel", and the interview is still in the `to_evaluate` stage.

> [!WARNING]
>
> Each condition inside an `OR` (or `AND`) array must be its **own object**. Putting multiple fields inside a single object — e.g. `OR: [{ email: {...}, firstName: {...}, lastName: {...} }]` — does **not** OR them together; a single object with multiple keys is combined with AND semantics, so all of those fields would need to match on the same record.

**Rule of thumb:**

* Use `OR` alone for simple "either/or" matching.
* Wrap it in `AND` when you want to combine multiple logical groups.

> [card] [Learn next?](https://docs.hireflix.com/tech/features/interviews/fetching-interview-results.md)
>
> Let's learn how to fetch results for an interview.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.