Public API for Reporting and Agentic Analysis

The MX8 Labs Research Platform API gives developers and analysts programmatic access to survey data and reports. It's read-only and designed for integration into your existing tools and workflows.

Common Use Cases

You might use the API to:

Integrate with BI/reporting tools like Power BI, Tableau, or Looker
Feed survey data into an LLM for summarization, comparison, or narrative generation
Automate QA or alerting on survey response rates and delivery
Compare survey waves or pull historical data snapshots
Power internal dashboards without needing direct access to the UI

API Documentation

Interactive OpenAPI docs:

Try the interactive API docs

Authentication

Every request requires either:

Bearer token (via Auth0)
API key in the access_token header. To request an API key, use the Intercom chat at the bottom left of the MX8 Labs Research Platform.

Endpoints Overview

1. List Surveys

GET /v2/surveys

Purpose: Fetch a list of all available surveys your account can access. Use Case: Useful when syncing surveys into a third-party tool or browsing metadata before selecting a survey to report on.

Sample Response

json
[
  {
    "id": 101,
    "name": "Brand Tracker 2025 Q1",
    "project": "Acme",
    "current_responses": 420,
    "target_responses": 500,
    "last_response": "2025-06-25T11:32:00Z"
  },
  {
    "id": 102,
    "name": "Concept Test - Ad Variant B",
    "project": "Globex",
    "current_responses": 300,
    "target_responses": 300,
    "last_response": "2025-06-27T16:14:43Z"
  }
  // ...
]

2. Get Survey Details

GET /v2/surveys/{survey_id}

Purpose: Retrieve detailed metadata for a single survey, including the question set and internal code. Use Case: When configuring automated reporting or generating a dynamic UI for cross-tab setup.

Sample Response

json
{
  "id": 101,
  "name": "Brand Tracker 2025 Q1",
  "project": "Acme",
  "current_responses": 420,
  "target_responses": 500,
  "last_response": "2025-06-25T11:32:00Z",
  "code": "...",
  "questions": [
    {
      "id": 1001,
      "question_text": "Which of these brands do you recognize?",
      "reporting_label": "Brand Recognition"
    },
    {
      "id": 1002,
      "question_text": "Which of these have you purchased in the last 30 days?",
      "reporting_label": "Recent Purchase"
    }
    // ...
  ]
}

3. Run a Report

POST /v2/surveys/{survey_id}/report

Purpose: Generate a cross-tab report based on a specific configuration of rows and columns. Use Case: Core endpoint for pulling real-time reporting data into external tools, or piping data into LLMs for analysis.

Request Body

json
{
  "row_ids": [1001],
  "column_ids": [1002]
}

This endpoint currently accepts only row_ids and column_ids. It uses the configured default aggregation for each question and does not accept an aggregation override such as numeric_median or selected_count_median. Choose those calculations in the report editor when building reports in the platform; they cannot currently be requested through this public endpoint. Their canonical identifiers and eligibility rules are documented in Question aggregation types for service integrations that consume the versioned reporting runtime contract.

Sample Response

json
{
  "headerColumns": [
    {
      "key": "recent_purchase",
      "title": "Recent Purchase",
      "headers": {
        "Acme Cola": "Acme Cola",
        "Globex Cola": "Globex Cola"
      }
    }
    // ...
  ],
  "valueColumns": [
    {
      "key": "brand_recognition",
      "title": "Brand Recognition",
      "headers": {
        "Acme Cola": "Acme Cola",
        "Globex Cola": "Globex Cola"
      }
    }
    // ...
  ],
  "rows": [
    {
      "id": "row-1",
      "headerValues": ["Acme Cola"],
      "columnValues": [
        {
          "key": "brand_recognition",
          "n": 150,
          "val": 0.76,
          "err": 0.04,
          "type": "pct_bar",
          "max": 1,
          "stat_test": null
        }
        // ...
      ]
    }
    // ...
  ]
}

Error Handling

All endpoints may return:

422 Validation Error: usually indicates malformed input
Errors include location (loc), message (msg), and type (type) for easier debugging

Questions?

Use the chat at the bottom-left of this page to get help or request access credentials.