Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pingcap/tidb/llms.txt

Use this file to discover all available pages before exploring further.

All endpoints are served on the TiDB status port (default 10080). See HTTP API Overview for base URL and security notes.
Administration endpoints can change server behavior at runtime. Restrict access to this port in production environments.

​
POST /settings

Updates one or more runtime settings. Send parameters as application/x-www-form-urlencoded form data.

​
Enable or disable general query log

# Enable
curl -X POST -d "tidb_general_log=1" http://127.0.0.1:10080/settings

# Disable
curl -X POST -d "tidb_general_log=0" http://127.0.0.1:10080/settings

​
Change log level

curl -X POST -d "log_level=debug" http://127.0.0.1:10080/settings
curl -X POST -d "log_level=info"  http://127.0.0.1:10080/settings
Supported log levels: debug, info, warn, error.

​
DDL slow log threshold

Sets the threshold (in milliseconds) above which DDL operations are recorded as slow: 
curl -X POST -d "ddl_slow_threshold=300" http://127.0.0.1:10080/settings

​
Async commit and one-phase commit

# Enable async commit
curl -X POST -d "tidb_enable_async_commit=1" http://127.0.0.1:10080/settings

# Enable 1PC
curl -X POST -d "tidb_enable_1pc=1" http://127.0.0.1:10080/settings

​
Deadlock history settings

# Set history table capacity
curl -X POST -d "deadlock_history_capacity=64" http://127.0.0.1:10080/settings

# Collect retryable deadlocks
curl -X POST -d "deadlock_history_collect_retryable=true" http://127.0.0.1:10080/settings

​
Transaction summary settings

# Minimum duration threshold for transaction digest collection (ms)
curl -X POST -d "transaction_id_digest_min_duration=500" http://127.0.0.1:10080/settings

# Transaction summary table capacity
curl -X POST -d "transaction_summary_capacity=256" http://127.0.0.1:10080/settings

​
GET /ddl/history

Returns the DDL job history. By default, returns up to 2048 jobs. 
curl http://127.0.0.1:10080/ddl/history

​
Pagination

# Limit the number of results
curl "http://127.0.0.1:10080/ddl/history?limit=50"

# Start from a specific job ID
curl "http://127.0.0.1:10080/ddl/history?start_job_id=1000&limit=50"
​
[].id
integer
Unique DDL job ID. Jobs are returned in reverse chronological order.
​
[].type
string
DDL operation type, for example create table, add index, drop column.
​
[].state
string
Final job state: synced, cancelled, or rollback done.
​
[].schema_name
string
Database the DDL job operated on.
​
[].table_name
string
Table the DDL job operated on.

​
POST /ddl/owner/resign

Instructs the current TiDB node to resign from the DDL owner role, triggering a new owner election. 
curl -X POST http://127.0.0.1:10080/ddl/owner/resign
If the target node is not the current DDL owner, the response will be: This node is not a ddl owner, can't be resigned.
Use this endpoint to gracefully transfer DDL ownership before maintenance operations.

​
GET /binlog/recover

Resumes binlog writing after a Pump recovery. By default, the request blocks until all in-flight transactions in the skipped state are committed. 
curl http://127.0.0.1:10080/binlog/recover

{
    "Skipped": false,
    "SkippedCommitterCounter": 0
}
​
Skipped
boolean
false means binlog is not in a skipped state (normal). true means binlog is currently being skipped.
​
SkippedCommitterCounter
integer
Number of transactions currently committing in the skipped state. Wait until this reaches 0 before considering the recovery complete.

​
Query parameters

ParameterDescription
op=nowaitReturn immediately after binlog status is recovered, without waiting for skipped transactions to commit.
op=resetReset SkippedCommitterCounter to 0. Use when the counter is stuck due to an abnormal state.
op=statusReturn the current binlog recovery status without triggering recovery.
# Return immediately
curl "http://127.0.0.1:10080/binlog/recover?op=nowait"

# Check status only
curl "http://127.0.0.1:10080/binlog/recover?op=status"
A 400 response with body timeout means the request timed out before recovery completed.

​
POST /tables///reset-id

Resets the AUTO_INCREMENT counter for the specified table. 
curl -X POST http://127.0.0.1:10080/tables/mydb/orders/reset-id
Resetting the auto-increment ID can cause duplicate key errors if rows with higher IDs already exist. Only use this on empty tables or after purging all existing rows.

​
GET /debug/pprof/

Exposes Go runtime profiling endpoints compatible with go tool pprof. Useful for diagnosing CPU, memory, goroutine, and mutex contention issues. 
# List available profiles
curl http://127.0.0.1:10080/debug/pprof/
EndpointDescription
/debug/pprof/heapMemory heap profile
/debug/pprof/goroutineAll current goroutines
/debug/pprof/profile?seconds=30CPU profile (30-second sample)
/debug/pprof/mutexMutex contention profile
/debug/pprof/blockGoroutine blocking profile
# Capture a 30-second CPU profile and analyze with pprof
curl -o cpu.prof "http://127.0.0.1:10080/debug/pprof/profile?seconds=30"
go tool pprof cpu.prof

​
Debug ZIP bundle

For a comprehensive snapshot of the node’s state, download the debug zip: 
curl "http://127.0.0.1:10080/debug/zip?seconds=60" --output debug.zip
The zip includes:
  • Go heap profile (post-GC)
  • Go CPU profile (10s)
  • Go mutex profile
  • Full goroutine dump
  • TiDB configuration and version
The seconds parameter controls the CPU profiling duration (default: 10s).

​
POST /upgrade/

Controls TiDB smooth upgrade mode. Use this during rolling upgrades to prevent incompatible DDL operations. 
# Start smooth upgrade mode
curl -X POST http://127.0.0.1:10080/upgrade/start

# Finish smooth upgrade mode
curl -X POST http://127.0.0.1:10080/upgrade/finish

# Check current upgrade state
curl -X POST http://127.0.0.1:10080/upgrade/show

"success!"

​
GET /txn-gc-states

Returns the current GC (garbage collection) state for transactions. 
curl http://127.0.0.1:10080/txn-gc-states

​
GET /stats/dump//

Downloads the optimizer statistics for a table in JSON format, which can be used for offline analysis or importing into another cluster. 
curl http://127.0.0.1:10080/stats/dump/mydb/orders --output orders_stats.json
To download statistics as of a specific point in time: 
curl "http://127.0.0.1:10080/stats/dump/mydb/orders/20240101120000" --output orders_stats.json
The timestamp format is yyyyMMddHHmmss.

Build docs developers (and LLMs) love

Get started for freeTalk to us