> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start Pathway Translation

> Start an async job translating pathways into scenarios.

### Overview

Starts a background job that converts pathways into agent scenarios, using Bland's migration planner for entries in `translate` mode and the deterministic one-to-one conversion for the rest. The body takes either the pathway-selection shape of [Migrate Pathways](https://docs.bland.ai/api-v2/post/agents-migrate-pathways.md) (stored pathways only) or the persona shape of [Migrate Persona](https://docs.bland.ai/api-v2/post/agents-migrate-persona.md); a body containing `persona_id` is treated as a persona run. The response is `202` with a run record. Poll it with [Get Pathway Translation Run](https://docs.bland.ai/api-v2/get/agents-migrate-translations-run-id.md) and stop it with [Cancel Pathway Translation Run](https://docs.bland.ai/api-v2/post/agents-migrate-translations-run-id-cancellations.md).

Limited to 10 starts per hour per organization, counted together with [Migrate Pathway](https://docs.bland.ai/api-v2/post/agents-migrate.md) and [Stream Pathway Migration](https://docs.bland.ai/api-v2/post/agents-migrate-stream.md). At most 5 pathways per job may be in `translate` mode, and at most 3 jobs per organization may be active at once. Requires an admin, owner, operator, or prompter role.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Body Parameters

Send one of the two shapes below. If `persona_id` is present the persona shape is used and `pathways` is ignored.

**Pathway selection**

**pathways** `array` *required*

One to 20 entries, each referencing a stored pathway. Returns `400 INVALID_PATHWAYS` for an empty array or a malformed entry, `400 TOO_MANY_PATHWAYS` beyond 20, `400 INLINE_PATHWAY_NOT_SUPPORTED` if any entry carries an inline `pathway` graph, and `400 TOO_MANY_TRANSLATIONS` if more than 5 entries are in `translate` mode.

**entry fields**

**pathway\_id** `string` *required*

UUID of a pathway your organization owns.

**version** `integer`

Pin a specific version number (a positive integer). Defaults to the pathway's published production version, or its live graph when nothing is published.

**mode** `string` (default: one\_to\_one)

`translate` to have the planner re-architect the pathway into scenarios, or `one_to_one` for the deterministic conversion. Any mix is accepted within one job.

**name** `string`

Display name for the new agent when `create` is `true`. Whitespace is trimmed. Defaults to the pathway's name when exactly one pathway is given, otherwise `Migrated pathways`.

**create** `boolean` (default: true)

When `false`, the job produces scenario nodes only (returned in the run's `result.scenarios`) instead of creating an agent.

**Persona**

**persona\_id** `string` *required*

UUID of a persona in your organization. Its attached pathways become the job's items and its prompts and settings become the agent shell, so a persona run always creates an agent. Returns `400 INVALID_PERSONA_ID` if not a UUID, `404 PERSONA_NOT_FOUND` if no such persona exists in your organization, `422 PERSONA_HAS_NO_VERSION` if it has neither a published nor a draft version, `400 NO_PATHWAY_CONDITIONS` if it has no attached pathways (use [Migrate Persona](https://docs.bland.ai/api-v2/post/agents-migrate-persona.md) instead), and `400 TOO_MANY_PATHWAYS` if it has more than 20.

**name** `string`

Display name for the new agent. Defaults to the persona's name.

**pathway\_modes** `array`

One entry per attached pathway, in the persona's order, each `one_to_one` or `translate`. The length must match the persona's pathway count or the request returns `400 INVALID_PATHWAY_MODES`. Defaults to `translate` for every pathway. More than 5 `translate` entries returns `400 TOO_MANY_TRANSLATIONS`.

### Response

Returns `202` on success. Returns `429 TOO_MANY_ACTIVE_TRANSLATIONS` when 3 jobs are already active for your organization.

**data.run** `object`

The new run, always in `PENDING` status.

**run object**

**id** `string`

Unique identifier for the run. Pass it as `{run_id}` when polling or cancelling.

**status** `string`

`PENDING` on creation. Later one of `RUNNING`, `FINALIZING`, `COMPLETE`, `FAILED`, `CANCELLED`.

**total\_pathways** `integer`

Number of pathways in the job.

**completed\_pathways** `integer`

Pathways processed so far. `0` on creation.

**result** `null`

Always `null` until the run reaches a terminal state.

**error\_code** `string | null`

`null` on creation.

**error\_message** `string | null`

`null` on creation.

**created\_at** `string`

ISO 8601 timestamp of when the run was created.

**completed\_at** `null`

Always `null` until the run reaches a terminal state.

**errors** `null | array`

`null` on success, or a list of error objects if the request failed.

```json Response theme={null}
{
  "data": {
    "run": {
      "id": "eb732a2a-94a9-45ae-9def-ecbc56c4a5bf",
      "status": "PENDING",
      "total_pathways": 2,
      "completed_pathways": 0,
      "result": null,
      "error_code": null,
      "error_message": null,
      "created_at": "2026-09-10T20:01:12.530Z",
      "completed_at": null
    }
  },
  "errors": null
}
```

```json Too Many Translations theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "TOO_MANY_TRANSLATIONS",
      "message": "at most 5 pathways can be AI-translated in one job — split the selection or switch some to 1:1"
    }
  ]
}
```

```json Too Many Active Jobs theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "TOO_MANY_ACTIVE_TRANSLATIONS",
      "message": "at most 3 translation jobs can run at once — wait for one to finish or cancel it"
    }
  ]
}
```

```json Rate Limited theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "TOO_MANY_REQUESTS",
      "message": "Too many pathway migrations started for this organization — please wait before starting another."
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.