# HTTP API

Send SQL queries to the Spice Cloud HTTP API at /v1/sql, and learn its API key requirement, row limit, and request timeout.

Post a SQL query to the `/v1/sql` API to query data.

## Requirements and limitations

- An API key is required for all SQL queries.
- Results are limited to 500 rows. Use the [Apache Arrow Flight API](https://spice.ai/docs/cloud/api/sql-query/apache-arrow-flight-api) to fetch up to 1M rows in a single query or the Async HTTP API to fetch results with paging.
- Requests are limited to 90 seconds.

### SQL Query

`POST /v1/sql`

Execute a SQL query and return the results.

This endpoint allows users to execute SQL queries directly from an HTTP request. The SQL query is sent as plain text in the request body.

#### Header parameters

- `X-API-Key` (string, required): Your project API key. See [API keys](https://spice.ai/docs/cloud/portal/apps/api-keys).
- `Accept` (string, required): The format of the response, one of 'application/json' (default), 'application/vnd.spiceai.sql.v1+json', 'text/csv' or 'text/plain'.

#### Request body

Required.

SQL query to execute

Content type: `application/json`

Type: `any`

Content type: `text/plain`

Type: `string`

Example:

```text
SELECT avg(total_amount), avg(tip_amount), count(1), passenger_count FROM my_table GROUP BY passenger_count ORDER BY passenger_count ASC LIMIT 3
```

#### Example request

```bash
curl -X POST "https://data.spiceai.io/v1/sql" \
  -H "X-API-Key: <project-api-key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT :foo + 1 AS the_answer",
    "parameters": {
      "foo": 41
    }
  }'
```

```http
POST /v1/sql HTTP/1.1
Host: data.spiceai.io
X-API-Key: <project-api-key>
Accept: application/json
Content-Type: application/json
Content-Length: 81

{
  "sql": "SELECT :foo + 1 AS the_answer",
  "parameters": {
    "foo": 41
  }
}
```

#### Responses

**200 OK**

SQL query executed successfully

Content type: `application/json`

Type: `array of any`

Example:

```json
[
  {
    "AVG(my_table.tip_amount)": 3.072259971396793,
    "AVG(my_table.total_amount)": 25.327816939456525,
    "COUNT(Int64(1))": 31465,
    "passenger_count": 0
  },
  {
    "AVG(my_table.tip_amount)": 3.3712622884680057,
    "AVG(my_table.total_amount)": 26.205230445474996,
    "COUNT(Int64(1))": 2188739,
    "passenger_count": 1
  },
  {
    "AVG(my_table.tip_amount)": 3.7171302113290854,
    "AVG(my_table.total_amount)": 29.520659930930304,
    "COUNT(Int64(1))": 405103,
    "passenger_count": 2
  }
]
```

Content type: `text/csv`

Type: `string`

Example:

```text
"AVG(my_table.tip_amount)","AVG(my_table.total_amount)","COUNT(Int64(1))","passenger_count"
3.072259971396793,25.327816939456525,31465,0
3.3712622884680057,26.205230445474996,2188739,1
3.7171302113290854,29.520659930930304,405103,2
```

Content type: `text/plain`

Type: `string`

Example:

```text
            +----------------------------+----------------------------+----------------+---------------------+
            | "AVG(my_table.tip_amount)"  | "AVG(my_table.total_amount)" | "COUNT(Int64(1))" | "passenger_count"   |
            +----------------------------+----------------------------+----------------+---------------------+
            | 3.072259971396793           | 25.327816939456525         | 31465          | 0                   |
            +----------------------------+----------------------------+----------------+---------------------+
            | 3.3712622884680057          | 26.205230445474996         | 2188739        | 1                   |
            +----------------------------+----------------------------+----------------+---------------------+
            | 3.7171302113290854          | 29.520659930930304         | 405103         | 2                   |
            +----------------------------+----------------------------+----------------+---------------------+
```

Content type: `application/vnd.spiceai.sql.v1+json`

Type: `any`

Example:

```json
{
  "row_count": 3,
  "schema": {
    "fields": [
      {
        "name": "AVG(my_table.tip_amount)",
        "data_type": "Float64",
        "nullable": false,
        "dict_id": 0,
        "dict_is_ordered": false
      },
      {
        "name": "AVG(my_table.total_amount)",
        "data_type": "Float64",
        "nullable": false,
        "dict_id": 0,
        "dict_is_ordered": false
      },
      {
        "name": "COUNT(Int64(1))",
        "data_type": "Int64",
        "nullable": false,
        "dict_id": 0,
        "dict_is_ordered": false
      },
      {
        "name": "passenger_count",
        "data_type": "Int64",
        "nullable": false,
        "dict_id": 0,
        "dict_is_ordered": false
      }
    ]
  },
  "data": [
    {
      "AVG(my_table.tip_amount)": 3.072259971396793,
      "AVG(my_table.total_amount)": 25.327816939456525,
      "COUNT(Int64(1))": 31465,
      "passenger_count": 0
    },
    {
      "AVG(my_table.tip_amount)": 3.3712622884680057,
      "AVG(my_table.total_amount)": 26.205230445474996,
      "COUNT(Int64(1))": 2188739,
      "passenger_count": 1
    },
    {
      "AVG(my_table.tip_amount)": 3.7171302113290854,
      "AVG(my_table.total_amount)": 29.520659930930304,
      "COUNT(Int64(1))": 405103,
      "passenger_count": 2
    }
  ]
}
```

**400 Bad Request**

Invalid SQL query or malformed input

Content type: `text/plain`

Type: `string`

Example:

```text
Error reading query: invalid UTF-8 sequence
```

**500 Internal Server Error**

Internal server error

Content type: `text/plain`

Type: `string`

Example:

```text
Unexpected internal server error occurred
```

OpenAPI: [spiceai/spiceai v2.4.0](https://github.com/spiceai/spiceai/blob/v2.4.0/.schema/openapi.json)