HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

Query API reference

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.

Overview

The scope of the API includes the following endpoints:

MethodPathAction
POST/queriesCall this endpoint to create a query run.
GET/workspaces/:workspace_id/queriesCall this endpoint to list query runs for a workspace.
GET/queries/:query_idCall this endpoint to show a query run.
POST/queries/:query_id/actions/cancelCall this endpoint to cancel a query run.

Create a query run

This endpoint creates a new query run.

POST /queries

StatusResponseReason
201JSON API documentSuccessfully created a query run.
404JSON API error objectNot found or the user is unauthorized to perform this action.
422JSON API error objectMalformed request body, such as missing attributes and wrong types.
500JSON API error objectInternal system failure.

Request body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key pathTypeDefaultDescription
data.typestringMust be "queries".
data.attributes.sourcestringThe source of the query such as query content or reference.
data.attributes.variablesarray[{key, value}](empty array)Specifies an optional list of run-specific variable values. Refer to run-specific variables for details.
data.relationships.workspace.data.typestringMust be "workspaces".
data.relationships.workspace.data.idstringThe ID of the workspace to run the query against.
data.relationships.configuration-version.data.typestringMust be "configuration-versions".
data.relationships.configuration-version.data.idstringThe ID of the configuration version to use for the query.

Sample Payload

{
  "data": {
    "type": "queries",
    "attributes": {
      "source": "example-query-content",
      "variables": [
        { "key": "replicas", "value": "2" }
      ]
    },
    "relationships": {
      "workspace": {
        "data": {
          "type": "workspaces",
          "id": "ws-ABC123"
        }
      },
      "configuration-version": {
        "data": {
          "type": "configuration-versions",
          "id": "cv-XYZ789"
        }
      }
    }
  }
}

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/queries

Sample Response

{
  "data": {
    "id": "query-ABC123",
    "type": "queries",
    "attributes": {
      "actions": {
        "is-cancelable": true,
        "is-force-cancelable": false
      },
      "canceled-at": null,
      "updated-at": "2025-01-15T10:30:00.000Z",
      "created-at": "2025-01-15T10:30:00.000Z",
      "source": "example-query-content",
      "variables": [
        { "key": "replicas", "value": "2" }
      ],
      "status-timestamps": {
        "pending-at": "2025-01-15T10:30:00.000Z",
        "queued-at": null,
        "errored-at": null,
        "canceled-at": null,
        "running-at": null,
        "finished-at": null
      },
      "status": "pending",
      "log-read-url": "https://archivist.terraform.io/v1/object/...",
    },
    "relationships": {
      "workspace": {
        "data": {
          "type": "workspaces",
          "id": "ws-ABC123"
        }
      },
      "configuration-version": {
        "data": {
          "type": "configuration-versions",
          "id": "cv-XYZ789"
        }
      },
      "created-by": {
        "data": {
          "type": "users",
          "id": "user-123"
        }
      },
      "canceled-by": {
        "data": null
      }
    },
    "links": {
      "self": "/api/v2/queries/query-ABC123"
    }
  }
}

List query runs for a workspace

This endpoint lists query runs for a particular workspace.

GET /workspaces/:workspace_id/queries

ParameterDescription
:workspace_idThe ID of the workspace to list query runs for.

Query parameters

This endpoint supports pagination with standard URL query parameters. You must use percent-style encoding [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

ParameterDescription
page[number]Optional. If omitted, the endpoint returns the first page.
page[size]Optional. If omitted, the endpoint returns 20 query runs per page.
StatusResponseReason
200JSON API documentSuccessfully retrieved the list of query runs.
404JSON API error objectNot found or the user is unauthorized to perform this action.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/workspaces/ws-ABC123/queries

Sample Response

{
  "data": [
    {
      "id": "query-ABC123",
      "type": "queries",
      "attributes": {
        "canceled-at": null,
        "updated-at": "2025-01-15T10:35:00.000Z",
        "created-at": "2025-01-15T10:30:00.000Z",
        "source": "example-query-content", 
        "variables": [
          { "key": "replicas", "value": "2" }
        ],
        "status-timestamps": {
          "pending-at": "2025-01-15T10:30:00.000Z",
          "queued-at": "2025-01-15T10:30:05.000Z",
          "errored-at": null,
          "canceled-at": null,
          "running-at": "2025-01-15T10:30:10.000Z",
          "finished-at": "2025-01-15T10:35:00.000Z"
        },
        "status": "finished",
        "log-read-url": "https://archivist.terraform.io/v1/object/..."
      },
      "relationships": {
        "workspace": {
          "data": {
            "type": "workspaces",
            "id": "ws-ABC123"
          }
        },
        "configuration-version": {
          "data": {
            "type": "configuration-versions",
            "id": "cv-XYZ789"
          }
        },
        "created-by": {
          "data": {
            "type": "users",
            "id": "user-123"
          }
        },
        "canceled-by": {
          "data": null
        }
      },
      "links": {
        "self": "/api/v2/queries/query-ABC123"
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/v2/workspaces/ws-ABC123/queries?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/v2/workspaces/ws-ABC123/queries?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/v2/workspaces/ws-ABC123/queries?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 1
    }
  }
}

Show a query run

This endpoint shows details for a specific query run.

GET /queries/:query_id

ParameterDescription
:query_idThe ID of the query run to retrieve.
StatusResponseReason
200JSON API documentSuccessfully retrieved the query run.
404JSON API error objectNot found or the user is unauthorized to perform this action.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/queries/query-ABC123

Sample Response

{
  "data": {
    "id": "query-ABC123",
    "type": "queries",
    "attributes": {
      "actions": {
        "is-cancelable": true,
        "is-force-cancelable": false
      },
      "canceled-at": null,
      "updated-at": "2025-01-15T10:30:15.000Z",
      "created-at": "2025-01-15T10:30:00.000Z",
      "source": "example-query-content",
      "variables": [
        { "key": "replicas", "value": "2" }
      ],
      "status-timestamps": {
        "pending-at": "2025-01-15T10:30:00.000Z",
        "queued-at": "2025-01-15T10:30:05.000Z",
        "errored-at": null,
        "canceled-at": null,
        "running-at": "2025-01-15T10:30:10.000Z",
        "finished-at": null
      },
      "status": "running",
      "log-read-url": "https://archivist.terraform.io/v1/object/...",
    },
    "relationships": {
      "workspace": {
        "data": {
          "type": "workspaces",
          "id": "ws-ABC123"
        }
      },
      "configuration-version": {
        "data": {
          "type": "configuration-versions",
          "id": "cv-XYZ789"
        }
      },
      "created-by": {
        "data": {
          "type": "users",
          "id": "user-123"
        }
      },
      "canceled-by": {
        "data": null
      }
    },
    "links": {
      "self": "/api/v2/queries/query-ABC123"
    }
  }
}

Cancel a query run

This endpoint cancels a query run that is currently pending or running.

POST /queries/:query_id/actions/cancel

ParameterDescription
:query_idThe ID of the query run to cancel.
StatusResponseReason
202Empty bodySuccessfully canceled the query run.
409JSON API error objectFailed to transition query run to a canceled state.

Sample Request

$ curl\
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/queries/query-ABC123/actions/cancel

Query run attributes

Query runs have the following attributes:

Status

The status attribute indicates the current state of the query run. Possible values are:

  • pending: The query run has been created but is not yet queued for execution.
  • running: The query run is currently executing.
  • finished: The query run completed successfully.
  • canceled: The query run was canceled before completion.
  • errored: The query run encountered an error during execution.

Status timestamps

The status-timestamps object contains timestamps for when the query run entered each status:

Log read URL

The log-read-url attribute contains a URL to retrieve the logs for the query run.

Available Related Resources

The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:

Edit this page on GitHub