errors.queries.get

Read one statement: what sampled requests saw, what the database measured (pg_stat_statements), charts, and the database at one request’s minute

GET /errors/api/queriesIAM errors:GetEventsRead

A database counts only when the caller has rds:DescribeDBQueryInsights on it. Connections, locks and cache hit are sampled once a minute with the statements; minutes sampled before they were kept have them null.

Without rds:DescribeDBQueryInsights the answer is reduced rather than refused.

Request syntax

GET /errors/api/queries

Query parameters

  • fpRequired

    string

    The statement fingerprint, sqlfp1:<16 hex>, as the Queries tab and the database’s query insights show it

    Constraints: /^sqlfp1:[0-9a-f]{16}$/

  • projectOptional

    string

    Only this project (its id). Default: every project of the organization whose events you may read; a project you may not read leaves nothing to show (404)

    Constraints: uuid

  • rangeOptional

    enum

    Window counted back from now: the last 24 hours (default) or 7 days

    One of: 24h, 7d

    Default: "24h"

  • requestOptional

    string

    A sampled request (its transaction event id) whose minute `minute` describes. Default: the request with the slowest call

    Constraints: /^[0-9a-f]{32}$|^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/

  • atOptional

    string

    A minute for `minute` instead of a request’s (ISO 8601), e.g. a db span’s start

    Constraints: datetime

Response

200 with { fingerprint, range, statement, perProject, slowest, nPlusOne, samples, servers, databases, chart, bucketSeconds, minute }: `perProject` per project its calls, totalMs, maxMs, transactions and nPlusOne; `slowest` the 10 sampled requests with the slowest call, `samples` the 20 most recent and `nPlusOne` the 10 N+1 requests with the most calls (projectId, transactionEventId, traceId, transactionName, calls, totalMs, maxMs, startedAt, nPlusOne); `servers` up to 10 places it ran (serverAddress, serverPort, dbName, dbSystem, database: the matching managed database or null); `databases` per database you may read that measured it, connected to a project or where its spans ran (dbInstanceId, identifier, query, calls, totalMs, rows, sharedHit, sharedRead, tempWritten in 8 KiB blocks, maxMs and stddevMs since pg_stat_statements was last reset, places per database and role, series per bucket); `chart` per bucket of `bucketSeconds` dbCallsPerMinute and dbMeanMs (every call; null without a database), sampledCallsPerMinute and p95Ms (of each sampled request’s slowest call); `minute` the database in the minute in the middle of the slowest call of `request` (default the slowest request; `minute.request` its transactionEventId, traceId, transactionName, startedAt and maxMs) or at `at`: per database and node its connections, activeSessions, idleInTransaction, lockWaits, maxConnections, longestTransactionS, cacheHit (0–1), calls and totalMs, the median of the hour around it, and the 5 busiest statements of that minute (null without a request or `at`). 404 when no project you may read ran it and no database you may read measured it in the window.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow errors:GetEvents on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud errors queries get --fp example

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_errors_queries_get.