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

# Migrations

> Read and list migration details

# Migrations API

The Migrations API allows you to **read** and **list** migration details.

## Authentication

All API requests require authentication using an API key. For details on API keys and authentication, see the [API Authorization](/v1/guides/auth) guide.

<Note>Migrations are always initiated by users through the embedded modal interface. Your organization can only access data from migrations that have been initiated by your end users.</Note>

## Migration Data Structure

Migration data is returned in a structured JSON format that includes:

```json theme={"system"}
{
  "object": "migration",
  "id": "9f5b41bd-7c5e-42d9-b332-b31686e94424",
  "created": "2025-12-02T23:51:49.807119",
  "status": "COMPLETE",
  "created_by_user_id": "9876543210fedcba",
  "company_id": "abcdef1234567890"
}
```

### Migration Fields

The migration object contains the following fields:

| Field                | Description                                                                           |
| -------------------- | ------------------------------------------------------------------------------------- |
| `object`             | The type of object, always `migration`                                                |
| `id`                 | The unique identifier for the migration, used to reference the migration in API calls |
| `created`            | The ISO 8601 timestamp when the migration was created in the system                   |
| `status`             | The current status of the migration (see Status Values section below)                 |
| `created_by_user_id` | The unique identifier of the user who initiated the migration                         |
| `company_id`         | The unique identifier of the company associated with this migration                   |

## API Endpoints

### List All Migrations

To list all migrations for your organization:

<CodeGroup>
  ```javascript listMigrations.js theme={"system"}
  async function listMigrations() {
    const response = await fetch(`https://worker.anon.com/api/v1/migrations`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${ANON_API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    
    if (!response.ok) {
      throw new Error(`Error: ${response.status}`);
    }
    
    return await response.json();
  }
  ```

  ```shell listMigrations.sh theme={"system"}
  curl -X GET "https://worker.anon.com/api/v1/migrations" \
    -H "Authorization: Bearer ${ANON_API_KEY}" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

<Note>The API supports pagination using `page` and `page_size` query parameters. The default page size is 10 items per page. Use these parameters to navigate through large sets of migrations.</Note>

### Get a Specific Migration

To retrieve details about a specific migration given a `migrationId`:

<CodeGroup>
  ```javascript getMigration.js theme={"system"}
  async function getMigration(migrationId) {
    const response = await fetch(`https://worker.anon.com/api/v1/migrations/${migrationId}`, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${ANON_API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    
    if (!response.ok) {
      throw new Error(`Error: ${response.status}`);
    }
    
    return await response.json();
  }
  ```

  ```shell getMigration.sh theme={"system"}
  curl -X GET "https://worker.anon.com/api/v1/migrations/${MIGRATION_ID}" \
    -H "Authorization: Bearer ${ANON_API_KEY}" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

## Migration Status Values

Migrations can have the following status values:

* `NOT_STARTED`: Migration has been created but not started
* `WORKING`: Migration is in progress
* `PENDING_USER_INPUT`: Migration is waiting for user input
* `COMPLETE`: Migration has completed successfully
* `FAILED`: Migration has failed
* `COMPLETED_WITH_FAILURES`: Migration completed but with some failures

<Tip>Design your application to handle all possible migration status values, including edge cases like `FAILED` and `COMPLETED_WITH_FAILURES`.</Tip>

## Best Practices

* Monitor migration status regularly
* Implement proper error handling for failed migrations
* Keep your API key secure and never expose it in client-side code
* Handle all possible migration status values in your application