# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.csvgetter.com/the-export-url.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.