Segments

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

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

curl --request GET \
  --url 'https://api.minerva.io/v2/segments/members?segment_id=YOUR_SEGMENT_ID' \
  --header 'x-api-key: <api-key>'

Headers

x-api-key

string

required

Your API key for authentication

Query Parameters

segment_id

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.

page

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).

Request Example

# 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.

api_request_id

string

Unique identifier for this API request, useful for debugging and support

results

object

Paginated results object containing the member list and pagination metadata

request_completed_at

string

ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SS.ffffffZ format) when the request completed

Results Object Structure

items

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.

total_count

integer

Total number of members in the segment across all pages. This is the segment’s current_size and represents the complete membership count.

page

integer

The current page number being returned (1-indexed). Matches the page query parameter you provided.

list_continues

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).

Member Object Structure

Each item in the items array contains:

minerva_pid

string

The Minerva person identifier for this segment member, in the format “p-”. Use this PID to enrich the person, retrieve their data, or remove them from the segment.

first_added_at

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.

{
  "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"
}

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:

{
  "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:

{
  "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

Pagination Guide

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

Start with page=1
Process the items in the response
Check the list_continues field
If true, increment page and repeat; if false, you’re done

Python Example:

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:

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 OR attempting to use v1 API version (only v2 supported)
405 - Method Not Allowed: Using POST, PUT, DELETE, or other methods (only GET supported)
422 - Unprocessable Entity: Missing segment_id query parameter OR invalid page parameter (must be ≥ 1)
500 - Internal Server Error: Unexpected server error occurred

Error Examples

Segment not found:

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

Missing segment_id:

{
  "error": "Request parameters must contain a 'segment_id' field",
  "status_code": 422
}

Invalid page number:

{
  "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

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

Add Members - Add people to the segment
Remove Members - Remove people from the segment
Enrich API - Get detailed data for the Minerva PIDs returned
Death Signals - Get death signals for segment members

Getting Started

Core Endpoints

Validation Workflows

Segments - Members

Quick Answer

Overview

Headers

Query Parameters

Request Example

Response

Success Response

Results Object Structure

Member Object Structure

Error Responses

Error Examples

Implementation Notes

Performance Characteristics

Common Integration Patterns

Getting Started

Core Endpoints

Validation Workflows

Segments

​Quick Answer

​Overview

​Headers

​Query Parameters

​Request Example

​Response

​Success Response

​Results Object Structure

​Member Object Structure

​Pagination Guide

​Error Responses

​Error Examples

​Implementation Notes

​Performance Characteristics

​Common Integration Patterns

​Related Endpoints

Quick Answer

Overview

Headers

Query Parameters

Request Example

Response

Success Response

Results Object Structure

Member Object Structure

Pagination Guide

Error Responses

Error Examples

Implementation Notes

Performance Characteristics

Common Integration Patterns

Related Endpoints