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

# Segments - Members

> Retrieve all members of a segment with pagination support

<div style={{ display: 'none' }} aria-hidden="false">
  ## Quick Answer

  **How do I get the members of a segment?** Use this endpoint to retrieve the list of people in a segment, including their Minerva PIDs and when they were added.

  **Common questions this endpoint answers:**

  * How do I get all members in a segment?
  * How do I export a segment's member list?
  * How do I see who's in my segment?
  * How can I retrieve the people I added to a segment?
  * How do I list all contacts in a group?
  * How can I paginate through a large segment?

  **What you get back:** List of Minerva PIDs with timestamps showing when each person was added to the segment. Results are paginated with 5,000 members per page.

  **Common use cases:**

  * Export segment membership for reporting or processing
  * Sync segment data to CRM or marketing platforms
  * Feed PIDs into enrichment or other workflows
  * Audit segment composition
</div>

## Overview

The Segments Members endpoint retrieves the complete list of people in a segment with their membership metadata. Results are paginated with a fixed page size of 5,000 members per page, making it efficient to export large segments or process members in batches.

**What You Get:**

* Complete list of Minerva PIDs for all segment members
* `first_added_at` timestamp showing when each person initially joined the segment
* Pagination metadata to traverse large segments
* Total member count across all pages

<RequestExample>
  ```bash Request Example theme={null}
  curl --request GET \
    --url 'https://api.minerva.io/v2/segments/members?segment_id=YOUR_SEGMENT_ID' \
    --header 'x-api-key: <api-key>'
  ```
</RequestExample>

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

### Query Parameters

<ParamField query="segment_id" type="string" required>
  The UUID of the segment to retrieve members from (obtained from the segments/create endpoint). The segment must exist and belong to your organization.
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination, starting from 1 (not 0). Default is 1 if not specified. Each page returns up to 5,000 members (fixed limit).
</ParamField>

### Request Example

```bash theme={null}
# Get first page of members (PIDs 1-5000)
GET /v2/segments/members?segment_id=550e8400-e29b-41d4-a716-446655440000&page=1

# Get second page of members (PIDs 5001-10000)
GET /v2/segments/members?segment_id=550e8400-e29b-41d4-a716-446655440000&page=2

# Page parameter defaults to 1 if omitted
GET /v2/segments/members?segment_id=550e8400-e29b-41d4-a716-446655440000
```

## Response

### Success Response

The API returns a paginated list of segment members with metadata.

<ResponseField name="api_request_id" type="string">
  Unique identifier for this API request, useful for debugging and support
</ResponseField>

<ResponseField name="results" type="object">
  Paginated results object containing the member list and pagination metadata
</ResponseField>

<ResponseField name="request_completed_at" type="string">
  ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SS.ffffffZ format) when the request completed
</ResponseField>

#### Results Object Structure

<ResponseField name="items" type="array">
  Array of member objects for the current page. Maximum 5,000 items per page. Empty array if the segment has no members or you've requested a page beyond the last one.
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of members in the segment across all pages. This is the segment's `current_size` and represents the complete membership count.
</ResponseField>

<ResponseField name="page" type="integer">
  The current page number being returned (1-indexed). Matches the `page` query parameter you provided.
</ResponseField>

<ResponseField name="list_continues" type="boolean">
  Indicates whether more pages exist. `true` means you should request the next page to get additional members. `false` means this is the last page (or the only page).
</ResponseField>

#### Member Object Structure

Each item in the `items` array contains:

<ResponseField name="minerva_pid" type="string">
  The Minerva person identifier for this segment member, in the format "p-{hash}". Use this PID to enrich the person, retrieve their data, or remove them from the segment.
</ResponseField>

<ResponseField name="first_added_at" type="string">
  ISO 8601 timestamp showing when this person was first added to the segment. This timestamp is preserved even if the person is removed and re-added later, providing historical continuity.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "api_request_id": "req_members456",
    "results": {
      "items": [
        {
          "minerva_pid": "p-a1b2c3d4e5f6",
          "first_added_at": "2024-01-10T14:30:00.000000Z"
        },
        {
          "minerva_pid": "p-x9y8z7w6v5u4",
          "first_added_at": "2024-01-11T09:15:00.000000Z"
        },
        {
          "minerva_pid": "p-m5n6o7p8q9r0",
          "first_added_at": "2024-01-12T16:45:00.000000Z"
        }
      ],
      "total_count": 12500,
      "page": 1,
      "list_continues": true
    },
    "request_completed_at": "2024-01-15T10:30:45.123456Z"
  }
  ```
</ResponseExample>

**Interpreting the Example:**

* **Page 1 of 3** (12,500 total members ÷ 5,000 per page = 3 pages)
* **3 members shown** (truncated for readability; actual response would have up to 5,000)
* **`list_continues: true`** indicates more pages exist (pages 2 and 3)
* Members are ordered by `first_added_at` descending (most recent additions first)

**Empty Segment Response:**

```json theme={null}
{
  "api_request_id": "req_members457",
  "results": {
    "items": [],
    "total_count": 0,
    "page": 1,
    "list_continues": false
  },
  "request_completed_at": "2024-01-15T10:31:22.456789Z"
}
```

**Last Page Response:**

```json theme={null}
{
  "api_request_id": "req_members458",
  "results": {
    "items": [
      {
        "minerva_pid": "p-final123",
        "first_added_at": "2024-01-08T12:00:00.000000Z"
      }
    ],
    "total_count": 10001,
    "page": 3,
    "list_continues": false
  },
  "request_completed_at": "2024-01-15T10:32:15.789012Z"
}
```

* Page 3 contains only 1 member (10,001 total = 5,000 + 5,000 + 1)
* `list_continues: false` indicates this is the final page

<Note>
  Error responses include `statusCode` and `body` fields for backward compatibility with existing integrations. These are deprecated — prefer reading the HTTP status code and the top-level `api_request_id` / `error_message` fields directly.
</Note>

<ResponseExample>
  ```json 400 theme={null}
  {
    "api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "error_message": "Request must contain 'segment_id' query parameter"
  }
  ```

  ```json 401 theme={null}
  {
    "api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901",
    "error_message": "Unauthorized"
  }
  ```

  ```json 404 theme={null}
  {
    "api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012",
    "error_message": "Segment abc123 does not exist"
  }
  ```

  ```json 422 theme={null}
  {
    "api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234",
    "error_message": "Request must contain 'segment_id' query parameter"
  }
  ```

  ```json 429 theme={null}
  {
    "api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345",
    "error_message": "You reached your total request-rate limit, please contact help@minerva.io for help"
  }
  ```
</ResponseExample>

## Pagination Guide

The endpoint uses a fixed page size of **5,000 members per page**. To retrieve all members from a large segment:

**Algorithm:**

1. Start with `page=1`
2. Process the `items` in the response
3. Check the `list_continues` field
4. If `true`, increment page and repeat; if `false`, you're done

**Python Example:**

```python theme={null}
segment_id = "550e8400-e29b-41d4-a716-446655440000"
page = 1
all_members = []

while True:
    response = minerva_api.get_segment_members(segment_id, page=page)
    members = response['results']['items']
    all_members.extend(members)
    
    print(f"Retrieved page {page}: {len(members)} members")
    
    if not response['results']['list_continues']:
        break  # Last page reached
    
    page += 1

print(f"Total members retrieved: {len(all_members)}")
```

**Pagination Calculation:**

* **Total pages** = `ceil(total_count / 5000)`
* **Current page range** = `[(page-1) * 5000 + 1, min(page * 5000, total_count)]`
* **More pages exist** = `page * 5000 < total_count`

## Error Responses

The API returns standard HTTP status codes with descriptive error messages:

* `400` - **Bad Request**: Missing `segment_id` query parameter
* `401` - **Unauthorized**: Invalid or missing API key in x-api-key header
* `404` - **Not Found**: Segment with the provided `segment_id` does not exist in your organization
* `422` - **Unprocessable Entity**: Missing `segment_id` query parameter OR invalid `page` parameter (must be ≥ 1)
* `429` - **Too Many Requests**: Rate limit exceeded
* `500` - **Internal Server Error**: Unexpected server error occurred

### Error Examples

**Segment not found:**

```json theme={null}
{
  "error": "Segment 550e8400-e29b-41d4-a716-446655440000 does not exist",
  "status_code": 404
}
```

**Missing segment\_id:**

```json theme={null}
{
  "error": "Request parameters must contain a 'segment_id' field",
  "status_code": 422
}
```

**Invalid page number:**

```json theme={null}
{
  "error": "Page must be greater than or equal to 1",
  "status_code": 422
}
```

## Implementation Notes

* **API Version**: Only v2 is supported. Using `/v1/segments/members` returns a 404 error.
* **HTTP Method**: Only GET requests are accepted.
* **Page Size**: Fixed at 5,000 members per page. This cannot be customized.
* **Page Indexing**: Pages are 1-indexed (first page is `page=1`, not `page=0`).
* **Ordering**: Members are sorted by `first_added_at` in descending order (most recent additions first).
* **Historical Timestamps**: The `first_added_at` timestamp is preserved across remove/re-add cycles, maintaining historical accuracy.
* **Empty Segments**: If a segment has no members, you'll get `items: []`, `total_count: 0`, and `list_continues: false`.
* **Out-of-Range Pages**: Requesting a page beyond the last page returns empty `items` with `list_continues: false`.

## Performance Characteristics

* **Response Time**: Typically 100-300ms per page
* **Consistency**: The `total_count` is computed from the segment metadata table (`current_size` field), so it's always accurate
* **Concurrency**: Safe to paginate while other operations (add/remove members) are happening; you might see slightly inconsistent results across pages if the segment is being modified during pagination
* **Rate Limiting**: Standard API rate limits apply

## Common Integration Patterns

**Pattern 1: Export to CSV**

```python theme={null}
import csv

segment_id = "550e8400-e29b-41d4-a716-446655440000"
with open('segment_export.csv', 'w', newline='') as csvfile:
    writer = csv.writer(csvfile)
    writer.writerow(['minerva_pid', 'first_added_at'])
    
    page = 1
    while True:
        response = minerva_api.get_segment_members(segment_id, page=page)
        for member in response['results']['items']:
            writer.writerow([member['minerva_pid'], member['first_added_at']])
        
        if not response['results']['list_continues']:
            break
        page += 1
```

## Related Endpoints

* [Add Members](/api-reference/segments-members-add) - Add people to the segment
* [Remove Members](/api-reference/segments-members-remove) - Remove people from the segment
* [Enrich API](/api-reference/enrich-v2) - Get detailed data for the Minerva PIDs returned
* [Death Signals](/api-reference/segments-signals-deaths) - Get death signals for segment members