---
title: "List threads"
method: GET
path: "/v1/finder/threads"
tags: ["RecruitAffiliates.ai"]
---

# List threads

`GET /v1/finder/threads`

## Request

- Base URL: `https://api.affiliaterail.com`
- URL: `https://api.affiliaterail.com/v1/finder/threads`
- Auth: HTTP bearer

Your Mailroom's threads: the ones that need a reply first, then newest first. A **thread** is one email conversation with one person. Message bodies never come back over the API. A test key gets an empty list.

**Scope:** `finder:read` (or `finder:write`)

## Query parameters

- `view` 'replies' | 'needs_reply' | 'snoozed' | 'all': `replies` (the default): every thread they've written on. `needs_reply`: their message is the latest and it's interested or a question. `snoozed`, or `all` for everything sent.
- `filter` 'interested' | 'questions' | 'not_now' | 'complaints' | 'wrong_person' | 'not_interested': One kind of reply
- `inbox_id` string: One mailbox, from `GET /settings`
- `owner_user_id` string: A teammate's `user_id` from `GET /team`, or `unassigned`
- `stage` 'saved' | 'contacting' | 'replied' | 'negotiating' | 'onboarding' | 'activated' | 'no_reply' | 'declined' | 'on_hold'
- `campaign_id` string: Prefixed id (`fca_…`)
- `limit` string: 1 to 100, default 25
- `cursor` string: `next_cursor` from the previous page, with the same filters

## Response `200`

Threads

- FinderThreadPage
  - `data` FinderThread[], required
    - `id` string, required: Prefixed id (`fth_…`)
    - `object` 'finder_thread', required
    - `prospect_id` string, nullable, required: The matched prospect, or null when the reply matches nobody yet
    - `name` string, nullable, required
    - `inbox_id` string, nullable, required
    - `inbox_address` string, required
    - `subject` string, nullable, required: Null once the 30-day mail expiry has cleared it
    - `reply_kind` string, nullable, required: What their latest message was: `positive`, `question`, `not_now`, `negative`, `wrong_person` or `angry`. Null if they haven't written.
    - `last_direction` 'inbound' | 'outbound' | 'null', nullable, required
    - `last_message_at` string, date-time, nullable, required: ISO-8601, UTC
    - `message_count` integer, required
    - `needs_reply` boolean, required
    - `snoozed_until` string, date-time, nullable, required: ISO-8601, UTC
    - `handled_at` string, date-time, nullable, required: ISO-8601, UTC
    - `stage` 'saved' | 'contacting' | 'replied' | 'negotiating' | 'onboarding' | 'activated' | 'no_reply' | 'declined' | 'on_hold' | 'null', nullable, required
    - `owner_user_id` string, nullable, required
    - `campaign_id` string, nullable, required
  - `has_more` boolean, required
  - `next_cursor` string, nullable, required: Pass as `cursor` with the same filters for the next page. Null on the last page.

## Other responses

- `400`: Invalid request
- `401`: Missing or unknown API key
- `402`: The organization's Recruit Affiliates plan does not include the API
- `403`: Key lacks the required scope
- `404`: No such object in your organization
- `409`: In conflict with the object's state, or the same idempotent request is still running
- `422`: The request was understood and refused
- `429`: Rate limited, by key or by organization: see Retry-After and X-RateLimit-Scope
- `501`: Not available to a test key (`sandbox_no_send`)

---

[API](https://skmtc.dev/affiliaterail/apis/affiliaterail-api.md) · [All operations](https://skmtc.dev/affiliaterail/apis/affiliaterail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/affiliaterail/apis/affiliaterail-api/revisions/ea41f345c092?raw)