Market Research API

Run persona-based research campaigns at scale. Define a cohort, ask your questions, and get structured qualitative data back.

Overview

Campaigns orchestrate interviews across multiple personas in a single workflow. You define the target personas, the interview questions, and execution parameters. SocioLogic handles the rest — scheduling interviews, aggregating responses, and producing exportable results.

All endpoints require authentication via the X-API-Key header.

Authentication

X-API-Key: pl_live_your_key_here

Pricing

Campaign pricing varies based on the number of personas and questions per interview:

Component	Cost
Campaign creation	Free
Per persona interview	$0.65 per message
Results export	Free
Example: 10 personas, 5 questions each	~$32.50

Endpoints

POST

/api/v1/campaigns

Create Campaign

Define a new research campaign with target personas and questions.

Request Body

{
  "name": "Q3 Product Feedback Study",
  "description": "Evaluate response to new pricing tiers",
  "persona_slugs": [
    "urban-tech-professional",
    "suburban-parent-moderate",
    "rural-small-business-owner"
  ],
  "questions": [
    "How do you currently evaluate pricing for SaaS products?",
    "What would make you upgrade to a higher tier?",
    "Describe your ideal pricing structure."
  ],
  "settings": {
    "include_memory": true,
    "randomize_order": false
  }
}

Example Request

curl -X POST "https://sociologic.ai/api/v1/campaigns" \
  -H "X-API-Key: pl_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Product Feedback Study",
    "persona_slugs": ["urban-tech-professional", "suburban-parent-moderate"],
    "questions": ["How do you evaluate SaaS pricing?"]
  }'

Response

{
  "id": "camp_a1b2c3d4",
  "name": "Q3 Product Feedback Study",
  "status": "draft",
  "persona_count": 2,
  "question_count": 1,
  "estimated_cost": "$1.30",
  "created_at": "2026-05-01T12:00:00Z"
}

POST

/api/v1/campaigns/:id/execute

Execute Campaign

Start running interviews for a campaign. Transitions the campaign from "draft" to "running".

Path Parameters

id — the campaign ID (e.g., "camp_a1b2c3d4")

Example Request

curl -X POST "https://sociologic.ai/api/v1/campaigns/camp_a1b2c3d4/execute" \
  -H "X-API-Key: pl_live_your_key_here"

Response

{
  "id": "camp_a1b2c3d4",
  "status": "running",
  "interviews_total": 2,
  "interviews_completed": 0,
  "started_at": "2026-05-01T12:05:00Z"
}

GET

/api/v1/campaigns/:id

Get Campaign Results

Retrieve campaign status and interview results.

Path Parameters

id — the campaign ID

Example Request

curl -X GET "https://sociologic.ai/api/v1/campaigns/camp_a1b2c3d4" \
  -H "X-API-Key: pl_live_your_key_here"

Response

{
  "id": "camp_a1b2c3d4",
  "name": "Q3 Product Feedback Study",
  "status": "completed",
  "interviews_total": 2,
  "interviews_completed": 2,
  "results": [
    {
      "persona_slug": "urban-tech-professional",
      "responses": [
        {
          "question": "How do you evaluate SaaS pricing?",
          "answer": "I typically compare the feature set against...",
          "tokens_used": 287
        }
      ]
    }
  ],
  "total_cost": "$1.30",
  "completed_at": "2026-05-01T12:08:00Z"
}

POST

/api/v1/campaigns/:id/export

Export Results

Export campaign results in CSV or JSON format.

Path Parameters

id — the campaign ID

Request Body

{
  "format": "csv"  // "csv" or "json"
}

Example Request

curl -X POST "https://sociologic.ai/api/v1/campaigns/camp_a1b2c3d4/export" \
  -H "X-API-Key: pl_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"format": "csv"}' \
  -o results.csv

MCP Access

Campaign endpoints will be available as composite tools via the SocioLogic Signal Relay MCP server in Phase 3. For now, use the REST API directly or compose individual persona tools in your AI client.

# Coming in Phase 3:
sociologic_create_campaign
sociologic_execute_campaign
sociologic_get_campaign_results
sociologic_export_campaign

Back to API docs · Persona Agents