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

[
  {
    "id": 101,
    "name": "Brand Tracker 2025 Q1",
    "project": "PepsiCo",
    "current_responses": 420,
    "target_responses": 500,
    "last_response": "2025-06-25T11:32:00Z"
  },
  {
    "id": 102,
    "name": "Concept Test - Ad Variant B",
    "project": "Nestlé",
    "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

{
  "id": 101,
  "name": "Brand Tracker 2025 Q1",
  "project": "PepsiCo",
  "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 recognise?",
      "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

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

Sample Response

{
  "headerColumns": [
    {
      "key": "recent_purchase",
      "title": "Recent Purchase",
      "headers": {
        "Pepsi": "Pepsi",
        "Coke": "Coke"
      }
    }
    // ...
  ],
  "valueColumns": [
    {
      "key": "brand_recognition",
      "title": "Brand Recognition",
      "headers": {
        "Pepsi": "Pepsi",
        "Coke": "Coke"
      }
    }
    // ...
  ],
  "rows": [
    {
      "id": "row-1",
      "headerValues": ["Pepsi"],
      "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.