> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coactive.ai/latest/docs-guides/deep-dives/programmatically-retrieve-sql-results/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coactive.ai/_mcp/server.

This tutorial focuses on programmatically retrieving SQL query results to extract metadata using the Coactive API and Coactive SQL Engine functionality.

## Step 1: Setting Up Authorization

### Retrieve and setup API Credentials

1. Refer to our API Authenication page

## Step 2: Submitting a Query

To automate queries, use the Coactive API’s asynchronous query submission functionality.

### Example Query Submission

Use the following curl command to submit a SQL query:

**`Curl`**

```bash Curl
curl -X POST https://api.coactive.ai/api/v1/queries \
        -H "Authorization: Bearer <CLIENT_ID>:<CLIENT_SECRET>" \
        -H "Content-Type: application/json" \
        -d '{"query": "SELECT * FROM coactive_table", \
              "dataset_id": "<DATASET_ID>" \
            }'
```

### API Response

The API responds with query details including the query\_id:

**`API_Response`**

```bash API_Response
{    "query_id": "<QUERY_ID>",    
        "status": "Queued",
        "dataset_id": "<DATASET_ID>"  }
```

## Step 3: Checking Query Status

To check the status of your query, use the query\_id returned in the previous response:

**`Curl`**

```bash Curl
curl https://api.coactive.ai/api/v1/queries/<QUERY_ID> \
      -H "Authorization: Bearer <CLIENT_ID>:<CLIENT_SECRET>"
```

### Example Status Response

**`wordwrap`**

```bash wordwrap
{"query_id": "<QUERY_ID>",
  "status": "Complete",
  "dataset_id": "<DATASET_ID>",
  "total_row_count": 100  }
```

## Step 4: Downloading Results

Once the query status is "Complete," retrieve the results download URL:

**`Curl`**

```bash Curl
curl https://api.coactive.ai/api/v1/queries/<QUERY_ID>/results \
      -H "Authorization: Bearer <CLIENT_ID>:<CLIENT_SECRET>"
```

### Example Response

The response provides a temporary link to download the results:

**`API Response`**

```bash API Response
{    "query_id": "<QUERY_ID>",
     "download_url": "https://api.coactive.ai/presigned/...."  }
```

### Notes

* The download link expires 15 minutes after it is generated (configurable via the `expiration_seconds` query parameter).

## Example: Full Query Execution Workflow

1. Submit a query via POST.

2. Use the query\_id to check the status of the query.

3. Once the status is "Complete," download the results.

---

##### Key Links

* [Coactive API Documentation – Create Query](https://docs.coactive.ai/api-reference/queries/create-query)

* [Coactive API Documentation – Get Query](https://docs.coactive.ai/api-reference/queries/get-query)

* [Coactive API Documentation – Get Query Results URL](https://docs.coactive.ai/api-reference/queries/get-query-results-url)