# Create and claim accounts for AI agents
> Use the MotherDuck signup API so an agent can create an account and get a token, then claim that account as a human owner.
An AI agent working in a sandbox can create its own MotherDuck account with a single API request, get back a token, and start querying right away. No browser, no signup form, and no human in the loop. When the work is worth keeping, a human claims the account through a link and becomes its owner.

This guide covers both halves of that flow: the agent creating the account, and the human claiming it.

## How it works

1. The agent sends a `POST` request to the signup endpoint.
2. The response bundles a `motherduck_token`, a `claim_org_url`, and a `how_to_use_motherduck` string that tells the agent how to connect.
3. The agent connects with the [DuckDB CLI](/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck/) and works in the account.
4. A human opens the `claim_org_url`, signs up or signs in, and takes ownership of the account.

The signup endpoint creates a Free Plan organization owned by a [service account](/key-tasks/service-accounts-guide/create-and-configure-service-accounts/) until a human claims it. Because it's on the Free Plan, an agent can provision an account without spending a user's trial credits during the 7-day free trial period.

## Create an account (agent)

Send a `POST` request to the signup endpoint. No request body is required.

```bash
curl -X POST https://new.motherduck.com
```

The response is JSON:

```json
{
  "motherduck_token": "eyJhbGci...5Ukxg",
  "claim_org_url": "https://app.motherduck.com/claim-org?inviteId=<invite_id>",
  "how_to_use_motherduck": "MotherDuck is a data warehouse for your data...",
  "region": "aws-us-east-1"
}
```

| Field | Description |
|-------|-------------|
| `motherduck_token` | Access token the agent uses to connect to MotherDuck. |
| `claim_org_url` | Link a human opens to take ownership of the account. |
| `how_to_use_motherduck` | Plain-language instructions the agent can read to connect and start working. |
| `region` | Region the account was created in. |

The `how_to_use_motherduck` field is written for the agent to consume directly. Passing it into the agent's context steers it toward the right connection pattern and features.

<details>
<summary>Full <code>how_to_use_motherduck</code> instructions</summary>

```text
MotherDuck is a datawarehouse for your data. You can store, share, analyse your data, create dashboards with the 'dive' feature, and create workflows like ingest + schedule jobs using the 'flight' feature.

To use MotherDuck you need to install the duckdb cli using following command: `curl https://install.duckdb.org | sh`
Connect to MotherDuck using the MotherDuck token you received: `motherduck_token=<motherduck-token-here>  duckdb "md:" `

This will connect you to MotherDuck and default to using my_db. Create as many new databases as you want, follow it by `USE <database_name>`.

Create tables in this database for your data
- from csv using: CREATE TABLE <table_name> AS SELECT * FROM '<filename>.csv';
- from parquet using: CREATE TABLE <table_name> AS SELECT * FROM '<filename>.parquet';

To know more about:
- Writing SQL to access MotherDuck, browse duckdb documentation here https://duckdb.org/docs/
- All the cloud functions of MotherDuck use https://motherduck.com/docs
- Creating dives browse: https://motherduck.com/docs/sql-reference/motherduck-sql-reference/ai-functions/dives/

To own the organization created here, simply paste the claim_org_url in the browser and sign up with your email address to claim it.
```

</details>

The exact text of `how_to_use_motherduck` is returned by the endpoint and can change over time. Read it from the live response rather than relying on the copy reproduced here.

### Connect with the token

Install the DuckDB CLI, set the token as an environment variable, and connect:

```bash
curl https://install.duckdb.org | sh
export motherduck_token='<motherduck_token>'
duckdb "md:"
```

The connection defaults to the `my_db` database. From here the agent can create databases, load data, and run queries like any other MotherDuck connection.

## Claim the account (human)

To keep an agent-created account, take ownership of it:

1. Copy the `claim_org_url` from the signup response.
2. Open it in a browser.
3. Sign up with your email address, or sign in if you already have a MotherDuck account.

Completing the flow makes you the owner of the organization, with full access to its databases and everything the agent built. The link works in one step, so there's no separate email invitation to wait for.

:::note
An agent can create more than one account in a single session. Claim each account you want to keep with its own `claim_org_url`.
:::

## Limitations

- Agent-created accounts are on the free plan.
- Accounts are created in a single region, shown in the `region` field of the response.
- Merging a claimed account into an organization you already own is not supported. Claiming creates ownership of the agent's organization as a separate organization.
- Some agent sandboxes restrict outbound network access, which can block requests to the signup endpoint. If a request fails, check whether the environment allows outbound HTTPS to `new.motherduck.com`.

## Next steps
- [Create a MotherDuck account](https://motherduck.com/create-motherduck-account/) - agent-oriented overview of the signup endpoint
- [Build analytics agents with MotherDuck](/key-tasks/ai-and-motherduck/building-analytics-agents/)
- [Connect to MotherDuck](/key-tasks/authenticating-and-connecting-to-motherduck/connecting-to-motherduck/) with the DuckDB CLI
- [Create dashboards with Dives](/key-tasks/ai-and-motherduck/dives/)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fkey-tasks%2Fai-and-motherduck%2Fagent-account-signup%2F&page_title=Create%20and%20claim%20accounts%20for%20AI%20agents&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.