# getPlan

> Part of the MAP Audio Music API docs. Index of every page: https://map.audio/developers/music-api/llms.txt. OpenAPI document: https://map.audio/developers/music-api/openapi.json.

`GET https://api.map.audio/v1/plans/{id}`

Get a plan

A stored plan: its spec, the candidates the rules planner ranked, and the presets it names. Plans never change; render one with POST /v1/renders and `plan`. Free.

Auth: `Authorization: Bearer` with an API key or a map.audio access token. MCP tool: `get_plan`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | A plan id (plan_…), from POST /v1/plans. Matches `^plan_[0-9A-HJKMNP-TV-Z]{26}$`. |

## Example

```sh
curl -sS "https://api.map.audio/v1/plans/plan_01M6BPRCC4FTKB29RFYD2JDKJQ" \
  -H "Authorization: Bearer $MAP_API_KEY" \
  -H "Map-Version: 2026-11-01"
```

### 200: A caller plan

```json
{
  "object": "plan",
  "id": "plan_01M6BPRCC4FTKB29RFYD2JDKJQ",
  "seed": 0,
  "prompt": null,
  "planner": {
    "kind": "caller",
    "version": "caller-1",
    "model": null
  },
  "candidates": [],
  "spec": {
    "product": "pam",
    "base": {
      "preset": "pam:factory/acid-sprinkle",
      "variation": 1
    },
    "tempo": 128,
    "morph": {
      "to": {
        "preset": "pam:factory/teknochonic"
      },
      "at": 0.35
    },
    "arrangement": {
      "kind": "loop",
      "bars": 8
    }
  },
  "createdAt": "2026-11-01T14:02:10.250Z",
  "provenance": {
    "aiModels": [],
    "presets": [
      "pam:factory/acid-sprinkle",
      "pam:factory/teknochonic"
    ]
  }
}
```

### 404: Not found

```json
{
  "error": {
    "type": "not_found",
    "code": "not_found",
    "message": "No plan with that id; plans come from POST /v1/plans, which returns the id.",
    "param": "id",
    "retryable": false,
    "jobId": null,
    "docUrl": "https://map.audio/developers/music-api/errors#not_found",
    "requestId": "9a3f7c2e5b1d8f40-LHR"
  }
}
```

## Responses

- `200`: The plan.
- `404`: Not found
- `default`: Any other error: `error.code` names it, `error.param` the field at fault, and `error.docUrl` its entry in the error catalogue.

## Errors

- [`not_found`](https://map.audio/developers/music-api/errors#not_found)
- [`invalid_request`](https://map.audio/developers/music-api/errors#invalid_request)