Start a query

Validates the SQL (400 invalid_query, with line and column) and queues it; a worker runs it. 429 too_many_queries (with Retry-After) when the organization's queue, or everyone's, is full; 429 quota_exceeded (with quota, never Retry-After) when an hourly quota is spent. With an Idempotency-Key, retrying the same request within 24 hours answers the first 202 again, with Idempotent-Replayed: true, and queues nothing; the same key with a different request is 409 idempotency_conflict, and while the first is still being admitted, 409 idempotency_in_progress (with Retry-After).

POST

https://audit.ezghcloud.com/v1/organizations/{orgId}/queries

View as Markdown

Authorization

apiKeyoptionalHTTP
oauthoptionalHTTP
sessionCookieoptionalAPI key in cookie

Path parameters

orgIdstringrequired
The organization.

format: uuid

Header parameters

Idempotency-Keyoptionalstring | null
1 to 200 printable ASCII characters, scoped to the organization and kept 24 hours.

Request bodyJSONrequired

sqlstringrequired
fromoptionalstring | null
Inclusive, RFC 3339.

format: date-time
tooptionalstring | null
Exclusive, RFC 3339.

format: date-time

Returns

202

Queued. Location names the query; poll it until it finishes.

JSON

queryIdstringrequired
format: uuid
statusstringrequired
"queued".

400

invalid_request, invalid_cursor, invalid_query (with line and column), or lookup_too_broad.

JSON

errorobjectrequired
6 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- columnoptionalinteger
  invalid_query: where the SQL went wrong.
- lineoptionalinteger
  invalid_query: where the SQL went wrong.
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.
- reasonoptionalstring
  query_failed: the query's own error code.

401

unauthenticated: no credential, or one that doesn't check out.

JSON

errorobjectrequired
6 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- columnoptionalinteger
  invalid_query: where the SQL went wrong.
- lineoptionalinteger
  invalid_query: where the SQL went wrong.
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.
- reasonoptionalstring
  query_failed: the query's own error code.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed.

JSON

errorobjectrequired
6 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- columnoptionalinteger
  invalid_query: where the SQL went wrong.
- lineoptionalinteger
  invalid_query: where the SQL went wrong.
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.
- reasonoptionalstring
  query_failed: the query's own error code.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON

errorobjectrequired
6 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- columnoptionalinteger
  invalid_query: where the SQL went wrong.
- lineoptionalinteger
  invalid_query: where the SQL went wrong.
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.
- reasonoptionalstring
  query_failed: the query's own error code.

409

query_not_finished (with Retry-After), query_failed (with reason), query_cancelled or query_finished.

JSON

errorobjectrequired
6 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- columnoptionalinteger
  invalid_query: where the SQL went wrong.
- lineoptionalinteger
  invalid_query: where the SQL went wrong.
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.
- reasonoptionalstring
  query_failed: the query's own error code.

413

payload_too_large: the body is over 1 MiB.

JSON

errorobjectrequired
6 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- columnoptionalinteger
  invalid_query: where the SQL went wrong.
- lineoptionalinteger
  invalid_query: where the SQL went wrong.
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.
- reasonoptionalstring
  query_failed: the query's own error code.

429

too_many_requests or too_many_queries, with Retry-After; or quota_exceeded (with quota), never with Retry-After.

JSON

errorobjectrequired
6 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- columnoptionalinteger
  invalid_query: where the SQL went wrong.
- lineoptionalinteger
  invalid_query: where the SQL went wrong.
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.
- reasonoptionalstring
  query_failed: the query's own error code.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON

errorobjectrequired
6 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- columnoptionalinteger
  invalid_query: where the SQL went wrong.
- lineoptionalinteger
  invalid_query: where the SQL went wrong.
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.
- reasonoptionalstring
  query_failed: the query's own error code.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON

errorobjectrequired
6 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- columnoptionalinteger
  invalid_query: where the SQL went wrong.
- lineoptionalinteger
  invalid_query: where the SQL went wrong.
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.
- reasonoptionalstring
  query_failed: the query's own error code.