Skip to main content
POST
/
v1
/
query
curl --request POST \
  --url https://api.dynamosql.com/v1/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sql": "SELECT * FROM myschema.orders LIMIT 10",
  "mode": "execute",
  "options": {
    "maxRows": 10
  }
}
'
{
  "success": true,
  "data": {
    "data": [
      [
        1,
        "Alice",
        "alice@example.com"
      ],
      [
        2,
        "Bob",
        "bob@example.com"
      ]
    ],
    "columns": [
      "id",
      "name",
      "email"
    ],
    "firstRowIdx": 0,
    "resumeIdx": 10,
    "planTime": 3,
    "execTime": 47
  },
  "error": "<string>",
  "detailedError": "<string>"
}
Required scope: query

​
Before You Start

  • See Query Modes for when to use execute vs plan and what each response field means.
  • See Pagination for how to page through large result sets using maxRows and resumeIdx.
  • See Response Formats to choose between row arrays and key-value objects.
  • See the SQL Reference for the full list of supported SQL features and current limitations.

​
Authentication

All requests require a bearer token obtained from POST /v1/auth/token. Pass it in the Authorization header: 
Authorization: Bearer YOUR_ACCESS_TOKEN
Both modes require the query scope.

Authorizations

​
Authorization
string
header
required

Bearer token obtained from POST /v1/auth/token. Pass in the Authorization header as Bearer <token>.

Body

application/json
​
sql
string
required

The SQL SELECT statement to execute or plan. DynamoSQL supports SELECT only; INSERT, UPDATE, DELETE, and DDL are not supported.

​
mode
enum<string>
default:execute

"execute" (default) runs the query and returns rows. "plan" returns the optimizer's plan without executing or consuming DynamoDB read capacity. API clients require the query scope.

Available options:
execute,
plan
​
options
object

Response

Query succeeded or returned a structured query error envelope.

​
success
enum<boolean>
required

true when the request was processed without errors, false otherwise. Always present.

Available options:
true
​
data
object
Example:
{
  "data": [
    [1, "Alice", "alice@example.com"],
    [2, "Bob", "bob@example.com"]
  ],
  "columns": ["id", "name", "email"],
  "firstRowIdx": 0,
  "resumeIdx": 10,
  "planTime": 3,
  "execTime": 47
}
​
error
string

Short error message. Present when success is false.

​
detailedError
string

Extended error detail. For SQL parse errors, includes the parser's verbose message with line and column position. May be absent even when error is present.