Skip to main content
GET
/
organizations
/
{organization}
/
databases
/
{database}
/
branches
/
{branch}
/
insights
List branch queries
curl --request GET \
  --url https://api.planetscale.com/v1/organizations/{organization}/databases/{database}/branches/{branch}/insights \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://api.planetscale.com/v1/organizations/{organization}/databases/{database}/branches/{branch}/insights"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.planetscale.com/v1/organizations/{organization}/databases/{database}/branches/{branch}/insights', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.planetscale.com/v1/organizations/{organization}/databases/{database}/branches/{branch}/insights",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.planetscale.com/v1/organizations/{organization}/databases/{database}/branches/{branch}/insights"

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("Authorization", "Bearer <token>")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.planetscale.com/v1/organizations/{organization}/databases/{database}/branches/{branch}/insights")
.header("Authorization", "Bearer <token>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.planetscale.com/v1/organizations/{organization}/databases/{database}/branches/{branch}/insights")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
{
  "type": "<string>",
  "current_page": 123,
  "next_page": 123,
  "next_page_url": "<string>",
  "prev_page": 123,
  "prev_page_url": "<string>",
  "data": [
    {
      "id": "<string>",
      "fingerprint": "<string>",
      "statement_type": "<string>",
      "keyspace": "<string>",
      "normalized_sql": "<string>",
      "syntax_highlighted_sql": "<string>",
      "multishard": true,
      "query_count": 123,
      "error_count": 123,
      "tables": [
        "<string>"
      ],
      "qualified_tables": [
        "<string>"
      ],
      "table_keyspaces": [
        {}
      ],
      "index_usages": [
        {}
      ],
      "routing_index_usages": [
        {}
      ],
      "sum_shard_queries": 123,
      "max_shard_queries": 123,
      "avg_shard_queries": 123,
      "sum_rows_read": 123,
      "sum_rows_affected": 123,
      "sum_rows_returned": 123,
      "rows_read_per_returned": 123,
      "rows_read_per_query": 123,
      "rows_returned_per_query": 123,
      "rows_affected_per_query": 123,
      "sum_total_duration_millis": 123,
      "sum_total_duration_percent": 123,
      "sum_cpu_duration_millis": 123,
      "sum_cpu_duration_percent": 123,
      "sum_io_duration_millis": 123,
      "sum_io_duration_percent": 123,
      "last_run_at": "<string>",
      "time_per_query": 123,
      "p50_latency": 123,
      "p99_latency": 123,
      "max_latency": 123,
      "egress_bytes": 123,
      "egress_bytes_per_query": 123,
      "max_egress_bytes": 123,
      "ingress_bytes": 123,
      "ingress_bytes_per_query": 123,
      "max_ingress_bytes": 123,
      "blocks_read": 123,
      "blocks_hit": 123,
      "block_cache_hit_ratio": 123,
      "blocks_dirtied": 123,
      "blocks_written": 123,
      "traffic_control_warnings": 123,
      "traffic_control_throttled": 123,
      "traffic_control_checked": 123
    }
  ]
}

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

organization
string
required

Organization name slug from list_organizations. Example: acme.

database
string
required

Database name slug from list_databases. Example: app-db.

branch
string
required

Branch name from list_branches. Example: main.

Query Parameters

q
string

Search query statistics by SQL pattern

from
string

Start time for filtering query statistics (ISO 8601 timestamp)

to
string

End time for filtering query statistics (ISO 8601 timestamp)

period
string

Time period for filtering query statistics (e.g., '1h', '24h')

sort
enum<string>

Field to sort by

Available options:
keyspace,
query,
lastRun,
count,
errorCount,
rowsRead,
rowsAffected,
rowsReturned,
rowsReadPerReturned,
rowsReadPerQuery,
rowsReturnedPerQuery,
rowsAffectedPerQuery,
totalTime,
cpuTime,
ioTime,
sumShardQueries,
maxShardQueries,
avgShardQueries,
table,
qualifiedTable,
tableKeyspace,
indexes,
routingIndexes,
p50Latency,
p99Latency,
maxLatency,
percentTime,
percentCpuTime,
percentIoTime,
egressBytes,
egressBytesPerQuery,
maxEgressBytes,
ingressBytes,
ingressBytesPerQuery,
maxIngressBytes,
blocksRead,
blocksHit,
blockCacheHitRatio,
blocksDirtied,
blocksWritten,
trafficControlWarnings,
trafficControlThrottled,
trafficControlChecked,
trafficControlBudgetsUsed
dir
enum<string>

Sort direction

Available options:
asc,
desc
tablet_type
enum<string>

Filter by tablet type

Available options:
primary,
replica,
rdonly
type
enum<string>

Filter by statement type

Available options:
SELECT,
INSERT,
UPDATE,
DELETE
fields
string[]

Specific fields to include in the response

page
integer
default:1

If provided, specifies the page offset of returned results

per_page
integer
default:25

If provided, specifies the number of returned results

Response

Returns query statistics summaries

type
string
required

The response type. Always "list" for paginated responses.

current_page
integer
required

The current page number

next_page
integer | null
required

The next page number, or null when this is the last page

next_page_url
string | null
required

The next page of results, or null when this is the last page

prev_page
integer | null
required

The previous page number, or null when this is the first page

prev_page_url
string | null
required

The previous page of results, or null when this is the first page

data
object[]
required