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

> Learn about using the Firebolt API to interact with Firebolt.

# REST API

Use the Firebolt REST API to execute queries on engines programmatically. Learn how to use the API, including authentication, working with engines and executing queries. A service account is required to access the API. Learn about [managing programmatic access to Firebolt](/guides/managing-your-organization/service-accounts).

## Create a service account and associate it with a user

Create a service account with organization administrator privilege,
i.e., the service account property\_is\_organization\_admin\_ must be *true*.
Next, create a user with role privileges you would like to have the service account
and associate the service account with the user.

## Use tokens for authentication

To authenticate Firebolt using the service accounts with the properties
as described above via Firebolt’s REST API, send the following request
to receive an authentication token:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl -X POST --location 'https://id.app.firebolt.io/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience=https://api.firebolt.io' \
--data-urlencode "client_id=${service_account_id}" \
--data-urlencode "client_secret=${service_account_secret}"
```

where:

| Property       | Data type | Description                                                                                             |
| :------------- | :-------- | :------------------------------------------------------------------------------------------------------ |
| client\_id     | TEXT      | The service [account ID](/guides/managing-your-organization/service-accounts#get-a-service-account-id). |
| client\_secret | TEXT      | The service [account secret](/guides/managing-your-organization/service-accounts#generate-a-secret).    |

**Response**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{
  "access_token":"access_token_value",
  "token_type":"Bearer",
  "expires_in":86400
}
```

In the previous example response, the following apply:

* The `access_token` is a unique token that authorizes your API requests that acts as a temporary key to access resources or perform actions. You can use this token to authenticate with Firebolt’s platform until it expires.
* The `token_type` is `Bearer`, which means that the access token must be included in an authorization header of your API requests using the format: `Authorization: Bearer <access_token>`.
* The token `expires_in` indicates the number of seconds until the token expires.

Use the returned access\_token to authenticate with Firebolt.

To run a query using the API, you must first obtain the URL of the engine you want to run on.

## Get the account gateway URL

Use the following endpoint to return the account gateway URL for `<account name>`.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl https://api.app.firebolt.io/web/v3/account/<account name>/engineUrl \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <access token>'
```

**Example:** `https://api.app.firebolt.io/web/v3/account/my-account/engineUrl`

**Response**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{
  "engineUrl":"<prefix>.api.us-east-1.app.firebolt.io"
}
```

You can use this URL for metadata queries (for example, looking up engine URLs in `information_schema.engines`) and for DDL that does not target a specific user engine.

## Get a user engine URL

Get a user engine URL by running the following query against the `information_schema.engines` table:

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
SELECT url 
FROM information_schema.engines 
WHERE engine_name='<engine_name>'
```

You can run the query using the account gateway URL with the following request:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl --location 'https://<account gateway URL>/query' \
--header 'Authorization: Bearer <access token>' \
--data 'SELECT url FROM information_schema.engines WHERE engine_name='\''my_engine'\'''
```

## Execute a query on a user engine

Use the following endpoint to run a query on a user engine:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl --location 'https://<user engine URL>&database=<database name>' \
--header 'Authorization: Bearer <access token>' \
--data '<SQL query>'
```

where:

| Property        | Data type | Description                                                    |
| :-------------- | :-------- | :------------------------------------------------------------- |
| user engine URL | TEXT      | The user engine URL ([retrieved here](#get-a-user-engine-url)) |
| database name   | TEXT      | The database to run the query                                  |
| SQL query       | TEXT      | Any valid SQL query                                            |

<Note>
  Queries are per request. To run multiple statement queries, separate queries each into one request.
</Note>

## API limits

### Request Size Limits

By default, Firebolt enforces a request size limit of 2 MiB per query on user engines. If you exceed this limit, you will get an error like:

```
413: Request body is larger than configured limit of 20971520 bytes. Please contact support if you need to send larger queries to support your workload
```

This limit is configurable, so please contact our support team if it is insufficient for your use-case.

**Note**: overriding this limit will disable the following features for large requests:

* Requests above 2 MiB will not be retried internally after transient network errors.
* Requests above 2 MiB will not be included in online upgrade verification.