---
title: "POST /api/exploration"
method: POST
path: "/api/exploration"
tags: ["/api/exploration"]
---

# POST /api/exploration

`POST /api/exploration`

## Request

- Base URL: `` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/exploration`
- Auth: API key in header `X-API-Key`

Create a new exploration with a single thread, persist the user's selected metrics, dimensions,
  and timelines, and stamp the thread as started. Also auto-creates a placeholder Summary
  document in the same collection. Actual planning is async; this endpoint returns immediately
  with an empty queries list. Clients should poll `GET /:id` until the queries appear and reach
  a terminal status.

  Accepts the per-area `:blocks` payload (one entry per Research-plan block), persisted
  verbatim, plus a thread-scoped `:timeline_ids`.

## Request body

- object
  - `blocks` object[], nullable
    - `dimensions` object[], nullable
      - `dimension-id` string, required: value must be a valid UUID.
      - `display-name` string, nullable
      - `effective-type` string, nullable
      - `semantic-type` string, nullable
    - `metrics` object[], nullable
      - `card_id` integer, required: value must be an integer greater than zero.
      - `dimension_mappings` MetabaseMetricsCoreDimensionMapping[], nullable
        - `dimension-id` string, required
        - `table-id` integer: Valid Table ID
        - `target` union, required
          - unknown[]
            - unknown
          - unknown[]
            - unknown
        - `type` 'table': Type of dimension mapping.
  - `collection_id` integer, nullable: value must be an integer greater than zero.
  - `description` string, nullable
  - `name` string, required: value must be a non-blank string between 1 and 254 characters.
  - `prompt` string, nullable
  - `timeline_ids` integer[], nullable

## Response `2XX`

Successful response

- MetabaseExplorationsApiHydratedExploration: Schema for an Exploration with hydrated creator and threads.
  - `archived` boolean
  - `can_delete` boolean
  - `can_restore` boolean
  - `can_write` boolean
  - `collection_id` integer, nullable: value must be an integer greater than zero.
  - `created_at` unknown
  - `creator` object, nullable
  - `creator_id` integer, required: value must be an integer greater than zero.
  - `description` string, nullable
  - `document` MetabaseExplorationsApiExplorationDocument: Schema for the Summary document attached to an exploration.
    - `archived` boolean
    - `content_type` string, required
    - `created_at` string, date-time, required: value must be a valid date/time/datetime
    - `creator_id` integer, required: value must be an integer greater than zero.
    - `exploration_id` integer, required: value must be an integer greater than zero.
    - `id` integer, required: value must be an integer greater than zero.
    - `is_placeholder` boolean, required
    - `name` string, required
    - `updated_at` string, date-time, required: value must be a valid date/time/datetime
  - `id` integer, required: value must be an integer greater than zero.
  - `name` string, required
  - `threads` MetabaseExplorationsApiHydratedThread[], nullable
    - `blocks` MetabaseExplorationsApiExplorationBlockNode[], nullable
      - `explore_filters` union[], nullable
        - union
          - object
            - `dimension_name` string, nullable
            - `display_value` string, required: value must be a non-blank string.
            - `field_ref` union, required
              - …
            - `operator` '=', required
            - `value` union, required
              - …
          - object
            - `dimension_name` string, nullable
            - `display_value` string, required: value must be a non-blank string.
            - `field_ref` union, required
              - …
            - `operator` 'between', required
            - `values` unknown[], required
              - …
      - `id` integer, required: value must be an integer greater than zero.
      - `name` string, nullable, required
      - `pages` MetabaseExplorationsApiExplorationPageNode[], required
        - `hidden` boolean, required
        - `id` integer, required: value must be an integer greater than zero.
        - `long_name` string, nullable, required
        - `name` string, nullable, required
        - `position` integer, required: value must be an integer greater or equal to than zero.
        - `query_ids` integer[], required
        - `starred` boolean, required
      - `position` integer, required: value must be an integer greater or equal to than zero.
    - `canceled_at` unknown
    - `completed_at` unknown
    - `exploration_id` integer, required: value must be an integer greater than zero.
    - `id` integer, required: value must be an integer greater than zero.
    - `position` integer, required: value must be an integer greater or equal to than zero.
    - `prompt` string, nullable
    - `queries` MetabaseExplorationsApiExplorationQuerySummary[], nullable
      - `card_id` integer, required: value must be an integer greater than zero.
      - `contextual_interestingness_score` number, nullable
      - `dimension_id` string, nullable, required
      - `dimension_name` string
      - `display` string, nullable
      - `entity_id` string, nullable
      - `error_message` string, nullable
      - `exploration_thread_id` integer, required: value must be an integer greater than zero.
      - `finished_at` unknown
      - `id` integer, required: value must be an integer greater than zero.
      - `interestingness_score` number, nullable
      - `name` string, nullable
      - `position` integer, required: value must be an integer greater or equal to than zero.
      - `query_type` string, required
      - `row_count` integer, nullable: value must be an integer greater or equal to than zero.
      - `segment_id` integer, nullable: value must be an integer greater than zero.
      - `segment_name` string, nullable
      - `started_at` unknown
      - `status` string, required
    - `source_page_id` integer, nullable: value must be an integer greater than zero.
    - `started_at` unknown
    - `status` 'pending' | 'running' | 'canceled' | 'empty' | 'failed' | 'completed' | 'forbidden', required
    - `timelines` object[], nullable
      - `position` integer: value must be an integer greater or equal to than zero.
      - `timeline` object, nullable
      - `timeline_id` integer, required: value must be an integer greater than zero.
  - `updated_at` unknown

## Other responses

- `4XX`: Client error response
- `5XX`: Server error response

## Changes

- **2026-11-04** `2e178f5a7934`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/metabase/apis/metabase-api/changes/api/exploration/post.md)

---

[API](https://skmtc.dev/metabase/apis/metabase-api.md) - [All operations](https://skmtc.dev/metabase/apis/metabase-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metabase/apis/metabase-api/revisions/2e178f5a7934?raw)