Skip to content

Commit 2ade602

Browse files
sowju-hashicorpsowju-hashicorp
committed
Adds docs for Query API
1 parent 3a17182 commit 2ade602

File tree

1 file changed

+65
-51
lines changed
  • content/terraform-docs-common/docs/cloud-docs/api-docs/queries

1 file changed

+65
-51
lines changed

‎content/terraform-docs-common/docs/cloud-docs/api-docs/queries/index.mdx‎

Lines changed: 65 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,21 @@
11
---
22
page_title: /queries API reference for HCP Terraform
3-
description: Use the HCP Terraform API's `/queries` to create and manage Query Runs.
3+
description: Call the HCP Terraform API's `/queries` endpoint to create and manage query runs.
44
tfc_only: true
55
---
66

77
[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200
88

99
[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201
1010

11+
[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202
12+
1113
[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400
1214

15+
[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
16+
17+
[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409
18+
1319
[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422
1420

1521
[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500
@@ -20,44 +26,44 @@ tfc_only: true
2026

2127
# Query API reference
2228

23-
Queries let you execute queries against your HCP Terraform workspaces to retrieve information about workspace resources and configurations. Query runs are asynchronous operations that can be monitored for status and results.
29+
Call query API endpoints to execute query runs against your HCP Terraform workspaces. Query runs retrieve information about workspace resources and configurations. They are asynchronous operations that you can monitor for status and results.
2430

2531
## Overview
2632

2733
The scope of the API includes the following endpoints:
2834

2935
| Method | Path | Action |
3036
|----------|-------------------------------------------------- |------------------------------------------------------------------------------------------------------------|
31-
| `POST` | `/queries` | Call this endpoint to [create a Query Run](#create-a-query-run). |
32-
| `GET` | `/queries/:query_id` | Call this endpoint to [show a Query Run](#show-a-query-run). |
33-
| `POST` | `/queries/:query_id/actions/cancel` | Call this endpoint to [cancel a Query Run](#cancel-a-query-run). |
34-
| `GET` | `/workspaces/:workspace_id/queries` | Call this endpoint to [list Query Runs for a Workspace](#list-query-runs-for-a-workspace). |
37+
| `POST` | `/queries` | Call this endpoint to [create a query run](#create-a-query-run). |
38+
| `GET` | `/queries/:query_id` | Call this endpoint to [show a query run](#show-a-query-run). |
39+
| `POST` | `/queries/:query_id/actions/cancel` | Call this endpoint to [cancel a query run](#cancel-a-query-run). |
40+
| `GET` | `/workspaces/:workspace_id/queries` | Call this endpoint to [list query runs for a workspace](#list-query-runs-for-a-workspace). |
3541

36-
## Create a Query Run
42+
## Create a query run
3743

3844
This endpoint creates a new query run.
3945

4046
`POST /queries`
4147

4248
| Status | Response | Reason |
4349
|---------|---------------------------|-----------------------------------------------------------------------|
44-
| [201][] | [JSON API document][] | Successfully created a Query Run. |
45-
| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. |
46-
| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). |
50+
| [201][] | [JSON API document][] | Successfully created a query run. |
51+
| [404][] | [JSON API error object][] | Not found or the user is unauthorized to perform this action. |
52+
| [422][] | [JSON API error object][] | Malformed request body, such as missing attributes and wrong types. |
4753
| [500][] | [JSON API error object][] | Internal system failure. |
4854

4955

50-
### Request Body
56+
### Request body
5157

52-
This POST endpoint requires a JSON object with the following properties as a request payload.
58+
This `POST` endpoint requires a JSON object with the following properties as a request payload.
5359

5460
Properties without a default value are required.
5561

5662
| Key path | Type | Default | Description |
5763
|---------------------------------------------------|---------|------------------|-------------------------------------------------------------------------------------------------------------|
5864
| `data.type` | string | | Must be `"queries"`. |
59-
| `data.attributes.source` | string | | The source of the query (e.g., query content or reference). |
60-
| `data.attributes.variables` | array[{key, value}] | (empty array) | Specifies an optional list of run-specific variable values. Refer to Run-Specific Variables for details. |
65+
| `data.attributes.source` | string | | The source of the query such as query content or reference. |
66+
| `data.attributes.variables` | array[{key, value}] | (empty array) | Specifies an optional list of run-specific variable values. Refer to run-specific variables for details. |
6167
| `data.relationships.workspace.data.type` | string | | Must be `"workspaces"`. |
6268
| `data.relationships.workspace.data.id` | string | | The ID of the workspace to run the query against. |
6369
| `data.relationships.configuration-version.data.type` | string | | Must be `"configuration-versions"`. |
@@ -164,29 +170,29 @@ $ curl\
164170
}
165171
```
166172

167-
## List Query Runs for a Workspace
173+
## List query runs for a workspace
168174

169-
This endpoint lists Query Runs for a particular workspace.
175+
This endpoint lists query runs for a particular workspace.
170176

171177
`GET /workspaces/:workspace_id/queries`
172178

173179
| Parameter | Description |
174180
|------------------|-------------------------------------------------------|
175-
| `:workspace_id` | The ID of the workspace to list Query Runs for. |
181+
| `:workspace_id` | The ID of the workspace to list query runs for. |
176182

177-
### Query Parameters
183+
### Query parameters
178184

179-
This endpoint supports pagination [with standard URL query parameters](/terraform/cloud-docs/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs.
185+
This endpoint supports pagination [with standard URL query parameters](/terraform/cloud-docs/api-docs#query-parameters). You must use percent-style encoding `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs.
180186

181187
| Parameter | Description |
182188
|----------------|------------------------------------------------------------------------------|
183-
| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. |
184-
| `page[size]` | **Optional.** If omitted, the endpoint will return 20 Query Runs per page. |
189+
| `page[number]` | Optional. If omitted, the endpoint returns the first page. |
190+
| `page[size]` | Optional. If omitted, the endpoint returns 20 query runs per page. |
185191

186192
| Status | Response | Reason |
187193
|---------|---------------------------|----------------------------------------------------------------|
188-
| [200][] | [JSON API document][] | Successfully retrieved the list of Query Runs. |
189-
| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. |
194+
| [200][] | [JSON API document][] | Successfully retrieved the list of query runs. |
195+
| [404][] | [JSON API error object][] | Not found or the user is unauthorized to perform this action. |
190196

191197
### Sample Request
192198

@@ -272,20 +278,20 @@ $ curl\
272278
}
273279
```
274280

275-
## Show a Query Run
281+
## Show a query run
276282

277-
This endpoint shows details for a specific Query Run.
283+
This endpoint shows details for a specific query run.
278284

279285
`GET /queries/:query_id`
280286

281287
| Parameter | Description |
282288
|-------------|------------------------------------------|
283-
| `:query_id` | The ID of the Query Run to retrieve. |
289+
| `:query_id` | The ID of the query run to retrieve. |
284290

285291
| Status | Response | Reason |
286292
|---------|---------------------------|----------------------------------------------------------------|
287-
| [200][] | [JSON API document][] | Successfully retrieved the Query Run. |
288-
| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. |
293+
| [200][] | [JSON API document][] | Successfully retrieved the query run. |
294+
| [404][] | [JSON API error object][] | Not found or the user is unauthorized to perform this action. |
289295

290296
### Sample Request
291297

@@ -356,20 +362,20 @@ $ curl\
356362
}
357363
```
358364

359-
## Cancel a Query Run
365+
## Cancel a query run
360366

361-
This endpoint cancels a Query Run that is currently pending or running.
367+
This endpoint cancels a query run that is currently pending or running.
362368

363369
`POST /queries/:query_id/actions/cancel`
364370

365371
| Parameter | Description |
366372
|-------------|--------------------------------------|
367-
| `:query_id` | The ID of the Query Run to cancel. |
373+
| `:query_id` | The ID of the query run to cancel. |
368374

369375
| Status | Response | Reason |
370376
|---------|---------------------------|-----------------------------------------------------------------------|
371-
| [202][] | Empty body | Successfully canceled the Query Run. |
372-
| [409][] | [JSON API error object][] | Failed to transition Query Run to a canceled state. |
377+
| [202][] | Empty body | Successfully canceled the query run. |
378+
| [409][] | [JSON API error object][] | Failed to transition query run to a canceled state. |
373379

374380
### Sample Request
375381

@@ -381,31 +387,39 @@ $ curl\
381387
https://app.terraform.io/api/v2/queries/query-ABC123/actions/cancel
382388
```
383389

384-
## Query Run Attributes
390+
## Query run attributes
385391

386-
Query Runs have the following attributes:
392+
Query runs have the following attributes:
387393

388394
### Status
389395

390-
The `status` attribute indicates the current state of the Query Run. Possible values are:
396+
The `status` attribute indicates the current state of the query run. Possible values are:
397+
398+
- `pending`: The query run has been created but is not yet queued for execution.
399+
- `running`: The query run is currently executing.
400+
- `finished`: The query run completed successfully.
401+
- `canceled`: The query run was canceled before completion.
402+
- `errored`: The query run encountered an error during execution.
403+
404+
### Status timestamps
405+
406+
The `status-timestamps` object contains timestamps for when the query run entered each status:
391407

392-
- `pending` - The Query Run has been created but not yet queued for execution.
393-
- `running` - The Query Run is currently executing.
394-
- `finished` - The Query Run has completed successfully.
395-
- `canceled` - The Query Run was canceled before completion.
396-
- `errored` - The Query Run encountered an error during execution.
408+
- `pending-at`: When the query run was created.
409+
- `queued-at`: When the query run was queued for execution.
410+
- `running-at`: When the query run started executing.
411+
- `finished-at`: When the query run completed successfully.
412+
- `errored-at`: When the query run encountered an error.
413+
- `canceled-at`: When the query run was canceled.
397414

398-
### Status Timestamps
415+
### Log read URL
399416

400-
The `status-timestamps` object contains timestamps for when the Query Run entered each status:
417+
The `log-read-url` attribute contains a URL to retrieve the logs for the query run.
401418

402-
- `pending-at` - When the Query Run was created.
403-
- `queued-at` - When the Query Run was queued for execution.
404-
- `running-at` - When the Query Run started executing.
405-
- `finished-at` - When the Query Run completed successfully.
406-
- `errored-at` - When the Query Run encountered an error.
407-
- `canceled-at` - When the Query Run was canceled.
419+
## Available Related Resources
408420

409-
### Log Read URL
421+
The GET endpoints above can optionally return related resources, if requested with the [`include`](/terraform/cloud-docs/api-docs#inclusion-of-related-resources) query parameter. The following resource types are available:
410422

411-
The `log-read-url` attribute contains a URL to retrieve the logs for the Query Run.
423+
- `created-by` - The user who created the query run.
424+
- `configuration-version` - The configuration version used for the query run.
425+
- `configuration_version.ingress_attributes` - The ingress attributes for the configuration version used for the query run.

0 commit comments

Comments
 (0)