# `new.motherduck.com` — Instant, Credential-Free MotherDuck Account

## What is MotherDuck?

MotherDuck is a modern, serverless data warehouse built on DuckDB. It's faster and significantly less expensive than [Snowflake](https://motherduck.com/vs/snowflake-alternative/), [BigQuery](https://motherduck.com/vs/bigquery-alternative/), or [Redshift](https://motherduck.com/vs/redshift-alternative/), and it's designed for humans, agents, and applications alike — AI native from the ground up. Every user and every agent gets their own isolated DuckDB instance (a "Duckling") that spins up in 100ms and shuts down when idle, so there's no cluster to provision and no compute to pay for while you're not querying.

For comparisons against other platforms including [Postgres](https://motherduck.com/vs/postgresql-alternative/), [Databricks](https://motherduck.com/vs/databricks-alternative/), and [ClickHouse](https://motherduck.com/vs/clickhouse-alternative/), see the full list at <https://motherduck.com/vs/>.

## What `new.motherduck.com` does

`new.motherduck.com` is a single endpoint that spins up a brand-new, fully working MotherDuck account in a few seconds, no sign-up form, no email/password, no OAuth flow, and no payment to MotherDuck. It's meant for quickly kicking the tires on MotherDuck (e.g. from a script, a CI job, an AI agent, or a terminal one-liner) before you ever create a "real," permanent account.

By sending a request to this endpoint, you are agreeing to MotherDuck's [Terms of Service](https://motherduck.com/terms-of-service/).

## How to call it

The endpoint only accepts `POST` requests (a `GET` will return information about the endpoint). No headers, or authentication are required.

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

That command generates a request like this on the wire:

```
POST / HTTP/2
Host: new.motherduck.com
User-Agent: curl/8.7.1
Accept: */*
```

## What you get back

The response is a JSON object that looks like this:

```json
{
  "motherduck_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "claim_org_url": "https://app.motherduck.com/claim-org?inviteId=<uuid>",
  "how_to_use_motherduck": "... plain-text quick-start instructions ...",
  "region": "aws-us-east-1"
}
```

| Field | Description |
|---|---|
| `motherduck_token` | A JWT access token for a brand-new MotherDuck user, created just for you. This is the credential you use to connect DuckDB (CLI, Python, or any other client) to MotherDuck. Treat it like a password — anyone with the token can read/write your ephemeral account's data. |
| `claim_org_url` | A one-time link you can open in a browser to convert this throwaway account into a permanent one under your own email address (see "Claiming the account" below). |
| `how_to_use_motherduck` | A short, plain-text quick-start guide (reproduced below) explaining how to install DuckDB and connect using the token. |
| `region` | The AWS region your ephemeral account and its data live in (e.g. `aws-us-east-1`). |

### The account itself

The token identifies a temporary, auto-generated user (an address under the `agent.motherduck.com` domain) with **read/write** access. A default database called `my_db` is ready to use immediately, and you can create additional databases as needed. Because nothing was tied to a real identity at creation time, the account is considered **ephemeral** — the intended path is either to use it briefly and discard it, or to claim it (below) and make it permanent.

## Using the `motherduck_token`

### DuckDB CLI

1. Install the DuckDB CLI if you don't already have it:
   ```bash
   curl https://install.duckdb.org | sh
   ```
2. Launch the CLI with the token set as an environment variable and open a MotherDuck connection with `md:`:
   ```bash
   motherduck_token=<motherduck-token-here> duckdb "md:"
   ```
   This connects you to MotherDuck and defaults to the `my_db` database. From there you can create new databases and switch to them with `USE <database_name>;`.

   Alternatively, you can skip the environment variable and pass the token directly in the connection string:
   ```bash
   duckdb "md:my_db?motherduck_token=<motherduck-token-here>"
   ```

### Python (`duckdb` client)

```python
import duckdb

# Option 1: token via environment variable (motherduck_token)
con = duckdb.connect("md:")

# Option 2: token passed explicitly
con = duckdb.connect("md:my_db", config={"motherduck_token": "<motherduck-token-here>"})

con.sql("SHOW DATABASES").show()
```

Once connected, you can load data straight into MotherDuck-backed tables, e.g.:

```sql
CREATE TABLE my_table AS SELECT * FROM 'my_file.csv';
CREATE TABLE my_table AS SELECT * FROM 'my_file.parquet';
```

## Loading data

Create tables directly from files:

- From CSV: `CREATE TABLE <table_name> AS SELECT * FROM '<filename>.csv';`
- From Parquet: `CREATE TABLE <table_name> AS SELECT * FROM '<filename>.parquet';`

## What the ephemeral account is good for

An ephemeral MotherDuck account is a real, working Duckling with full SQL — it's just not tied to a permanent identity yet. Two use cases in particular fit it well:

- **Ad-hoc data analysis with DuckDB SQL.** Point an LLM (or yourself) at data loaded into your ephemeral database and let it generate the SQL to explore it — sums, averages, outliers, window functions, and more. This works whether the data is a single flat table or several tables linked by common keys (i.e. relational data you can `JOIN` across), since DuckDB's SQL engine handles both equally well.
- **Visualization and BI apps built by LLMs, via MotherDuck Dives.** Dives let an LLM turn a natural-language prompt into an interactive dashboard, explorer, map, or data app backed by your data — no separate BI tool required. There's a wide range of what's possible; browse real examples in the [Dive Gallery](https://motherduck.com/dive-gallery/).

## SQL for data analysis and format conversion

DuckDB's SQL dialect is built to make analytical work concise — window functions, list/struct types, `SUMMARIZE`, `COLUMNS()` pattern matching, and native readers for CSV, JSON, and Parquet are all just SQL. A few examples of what's possible once you're connected:

```sql
-- Quick statistical profile of a table (min/max, nulls, quantiles, etc.)
SUMMARIZE my_table;

-- Select all columns except a few, without listing every other column
SELECT * EXCLUDE (height, weight) FROM ducks;

-- Select columns by regex pattern
SELECT COLUMNS('^dim_') FROM fact_table;

-- Convert a CSV to Parquet in one statement
COPY (SELECT * FROM read_csv_auto('data.csv')) TO 'data.parquet' (FORMAT PARQUET);
```

For a much larger library of community-contributed SQL (plus Python, R, and bash) examples covering data analysis, format conversion, string/regex parsing, sampling, and more, browse [DuckDB Snippets](https://duckdbsnippets.com/), a community site sponsored by MotherDuck.

## Learn more

- SQL/DuckDB reference: <https://duckdb.org/docs/>
- MotherDuck docs (all cloud features): <https://motherduck.com/docs>
- Creating AI-powered dashboards ("Dives"): <https://motherduck.com/docs/sql-reference/motherduck-sql-reference/ai-functions/dives/>
- Dive Gallery (example Dives): <https://motherduck.com/dive-gallery/>
- DuckDB Snippets (community SQL/Python/R/bash examples): <https://duckdbsnippets.com/>

## Claiming the account

The ephemeral account and its token are temporary and not tied to any person. If you want to keep the data and turn the account into a normal, permanent MotherDuck account, open the `claim_org_url` returned in the response in a browser:

```
https://app.motherduck.com/claim-org?inviteId=<uuid>
```

From there, sign up with your own email address to claim the organization — no credit card required. Claiming:

- Transfers ownership of the ephemeral organization (and any databases/tables you created) to your real MotherDuck account.
- Lets you manage the account going forward through the normal MotherDuck Web UI — inviting teammates, creating additional users/service accounts, managing billing, etc.
- Is a one-time action tied to that specific `inviteId` — if you don't claim it, the account remains an unclaimed, ephemeral account rather than being converted to a permanent one.

If you never claim it, treat the account and its token as disposable: don't rely on it for anything you need to keep long-term. It is cleaned up after 72 hours.

### What claiming unlocks

Claiming turns your throwaway account into a real, ongoing MotherDuck organization, which brings the full set of MotherDuck capabilities into scope, including:

- **Scaling, both directions.** Scale horizontally with read-scaling (fan a read-heavy workload out across multiple Ducklings) and vertically by moving to larger Duckling instance sizes as your data or concurrency grows.
- **Sharing.** Create datasets and share them with others in your organization, or publish them publicly, so others can run their own analysis against a common, shared copy of the data without duplicating storage.
- **[Flights](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/flights/)** — MotherDuck's agent-native, scheduled data pipelines. Flights let you ingest data on a schedule from virtually anything MotherDuck can reach: HTTP(S) sites, Amazon S3, Google Cloud Storage, or application APIs for tools like HubSpot, Marketo, Salesforce, SAP, Workday, QuickBooks, Google Ads, Google Analytics, PostHog, Asana, Slack, and more. Browse worked examples in the [Flights cookbook](https://motherduck.com/docs/cookbook/).
- **A 7-day free trial of the Business plan**, with full access to all features (unlimited service accounts, all Duckling compute sizes, read scaling, SSO, longer historical-data retention, and more), also with no credit card required to start it. After the trial ends, your organization isn't cut off — MotherDuck has a generous **Free Plan** you can continue on indefinitely at no cost, or you can upgrade to a paid Lite or Business plan if you need more. See the [pricing page](https://motherduck.com/product/pricing/) for full plan details.

## More for agents

If you're an AI agent (or building one) and want a single, comprehensive Markdown reference to MotherDuck rather than browsing individual pages, two are available:

- Main site content: <https://motherduck.com/llms-full.txt>
- Full documentation: <https://motherduck.com/docs/llms-full.txt>