Segments

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

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

GET

segments

members

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

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

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

string

required

Your API key for authentication

Query Parameters

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.

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.

string

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

object

Paginated results object containing the member list and pagination metadata

string

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

Results Object Structure

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.

integer

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

integer

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

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:

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.

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

Error responses include statusCode and body fields for backward compatibility with existing integrations. These are deprecated — prefer the HTTP status code and the top-level code / message / api_request_id fields directly. (The deprecated nested body still carries the legacy error_message.)

{
  "code": "bad_request",
  "message": "Request must contain 'segment_id' query parameter",
  "api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "code": "unauthorized",
  "message": "Unauthorized",
  "api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901"
}

{
  "code": "not_found",
  "message": "Segment abc123 does not exist",
  "api_request_id": "c3d4e5f6-a7b8-2345-cdef-123456789012"
}

{
  "code": "unprocessable_entity",
  "message": "Request must contain 'segment_id' query parameter",
  "api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234"
}

{
  "code": "rate_limit_reached",
  "message": "You reached your total request-rate limit, please contact help@minerva.io for help",
  "api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345"
}

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:

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:

{
  "code": "not_found",
  "message": "Segment 550e8400-e29b-41d4-a716-446655440000 does not exist"
}

Missing segment_id:

{
  "code": "unprocessable_entity",
  "message": "Request parameters must contain a 'segment_id' field"
}

Invalid page number:

{
  "code": "unprocessable_entity",
  "message": "Page must be greater than or equal to 1"
}

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

⌘I

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

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

​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