# The Export URL

### URL Anatomy

```
https://api.csvgetter.com/<endpoint_id>?type=json_records&sql=SELECT * FROM csvgetter WHERE status='Active'
└──────────┬──────────────┘└─────┬─────┘└────────────────────────────┬────────────────────────────────────┘
       Base URL              Endpoint ID                      URL Parameters
```

#### Base URL

All endpoint URLs use the same base:

```
https://api.csvgetter.com
```

#### Endpoint ID

A unique alphanumeric identifier generated when you create the endpoint. Examples:

```
https://api.csvgetter.com/abc123def456
https://api.csvgetter.com/0b6VSN8fXQ8U
```

There is also an alternate path format that works identically:

```
https://api.csvgetter.com/files/abc123def456
```

#### URL Parameters

Query parameters are appended after `?` and separated by `&`. They modify the output without changing the endpoint configuration.

***

### How Parameters Chain

You can combine any number of parameters by joining them with `&`:

```
https://api.csvgetter.com/abc123?type=json_records&sql=SELECT name, email FROM csvgetter&filename_timestamp=true
```

**Order doesn't matter.** These are equivalent:

```
?type=json_records&sql=SELECT * FROM csvgetter
?sql=SELECT * FROM csvgetter&type=json_records
```

#### URL Encoding

When your parameters contain special characters (spaces, quotes, etc.), they must be URL-encoded. Most HTTP clients and browsers do this automatically, but if you're building URLs manually:

| Character | Encoded      |
| --------- | ------------ |
| Space     | `%20` or `+` |
| `=`       | `%3D`        |
| `&`       | `%26`        |
| `'`       | `%27`        |
| `*`       | `%2A`        |
| `>`       | `%3E`        |
| `<`       | `%3C`        |

**Example — SQL query with spaces and comparisons:**

Raw SQL:

```sql
SELECT * FROM csvgetter WHERE age > 25 ORDER BY name
```

URL-encoded:

```
?sql=SELECT%20*%20FROM%20csvgetter%20WHERE%20age%20%3E%2025%20ORDER%20BY%20name
```

> **Tip:** Use the URL Wizard in the CSV Getter dashboard to build URLs with parameters automatically.
>
> **Tip:** You can also use our [URL encoder](https://www.csvgetter.com/url-encoder-decoder)

***

### Authentication

Endpoints can optionally require a Bearer token. When auth is enabled:

**Request with auth:**

```bash
curl -H "Authorization: Bearer your-secret-token" \
  https://api.csvgetter.com/abc123def456
```

**Without the header (or wrong token), you'll get:**

```json
{
  "error": "Authorization header is required",
  "help": "https://docs.csvgetter.com"
}
```

The Bearer token is set when configuring your endpoint in the dashboard. You can change it at any time.

#### Auth Error Responses

| Scenario                | Status Code | Error Message                         |
| ----------------------- | ----------- | ------------------------------------- |
| No Authorization header | 401         | `Authorization header is required`    |
| Missing `Bearer` prefix | 401         | `Invalid Authorization header format` |
| Wrong token             | 401         | `Invalid Authorization header`        |

***

### Complete Real-World Example

#### Scenario

You have an Airtable base tracking job applicants. You want to:

1. Get only applicants with status "Interview"
2. Return only their name, email, and application date
3. Output as JSON
4. Get an email notification when the export runs

#### The URL

```
https://api.csvgetter.com/abc123def456?type=json_records&sql=SELECT name, email, application_date FROM csvgetter WHERE status='Interview' ORDER BY application_date DESC&email_me=true
```

#### Broken down:

| Part       | Value                                                                                                         | Purpose                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Base URL   | `https://api.csvgetter.com/abc123def456`                                                                      | Your endpoint                                        |
| `type`     | `json_records`                                                                                                | Output as JSON array of objects                      |
| `sql`      | `SELECT name, email, application_date FROM csvgetter WHERE status='Interview' ORDER BY application_date DESC` | Filter to interviews, select 3 columns, sort by date |
| `email_me` | `true`                                                                                                        | Send you an email notification                       |

#### Response (200 OK)

```json
[
  {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "application_date": "2025-03-15"
  },
  {
    "name": "John Doe",
    "email": "john@example.com",
    "application_date": "2025-03-10"
  }
]
```

***

### Previewing vs. Live Hits

When you use the **URL Wizard** or preview an endpoint in the dashboard, CSV Getter returns a **sample** (up to 10 rows) and does **not** deduct a credit.

When you hit the URL directly (browser, code, cURL, Excel, etc.), it returns the **full dataset** and deducts 1 credit.

***

### Error Responses

All error responses are JSON objects with an `error` field and an HTTP status code:

```json
{
  "error": "Not enough credits. Login at csvgetter.com to purchase.",
  "help": "https://docs.csvgetter.com"
}
```

See Troubleshooting for a full list of error codes and solutions.

***

### Next Steps

* **URL Parameters** — Full reference for all parameters.
* **The SQL Parameter** — Master data filtering and transformation.
* **The Type Parameter** — All output formats explained.
* **Combining URL Parameters** — Real workflow recipes.