Segments - Members

​

Overview

• 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

• Export segment membership for downstream processing or external systems
• Sync segment data to CRM platforms, marketing automation tools, or data warehouses
• Audit segment composition and membership history
• Feed Minerva PIDs into enrichment or signal monitoring workflows
• Generate reports on segment demographics or characteristics

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

​

Headers

​

Query Parameters

​

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

​

Results Object Structure

​

Member Object Structure

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

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

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

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

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

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

• 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

• 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

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

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

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

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