Skip to main content
Execute SQL queries against Flipside’s data warehouse across 20+ chains.

​
Query Lifecycle

create → execute → poll → data/download

​
Quick Start

# Create and run a query
flipside query create "SELECT block_number, block_timestamp FROM ethereum.core.fact_blocks LIMIT 10"

​
Creating Queries

# Create a new saved query (returns query ID)
flipside query create "SELECT * FROM ethereum.core.fact_transactions LIMIT 100"

# Create with a name
flipside query create "SELECT * FROM ethereum.core.fact_blocks LIMIT 10" --name "Recent Blocks"

​
Executing Queries

# Execute a saved query (returns run ID)
flipside query execute <query-id>

# Check run status
flipside query-run status <run-id>

# Poll until complete
flipside query-run poll <run-id> --timeout 5m

# Get results
flipside query-run data <run-id>

​
Downloading Results

# Download as CSV
flipside query-run download <run-id> --output results.csv

# Download as JSON
flipside query-run download <run-id> --output results.json --format json

​
Query Commands

CommandDescription
flipside query create <sql>Create a new saved query
flipside query listList all saved queries
flipside query get <id>Get query details
flipside query update <id>Update query name or SQL
flipside query execute <id>Execute a query (creates a run)
flipside query runs <id>List all runs for a query
flipside query delete <id>Delete a query

​
Query Run Commands

CommandDescription
flipside query-run status <run-id>Get current status
flipside query-run result <run-id>Get metadata (row count, schema, timing)
flipside query-run data <run-id>Get paginated row data
flipside query-run download <run-id>Download as CSV or JSON
flipside query-run cancel <run-id>Cancel a running query
flipside query-run poll <run-id>Wait for completion

​
Example Workflow

# Create and execute in one flow
QUERY_ID=$(flipside query create "SELECT * FROM ethereum.core.fact_transactions LIMIT 100" --json | jq -r '.id')

RUN_ID=$(flipside query execute $QUERY_ID --json | jq -r '.id')

# Wait for completion and download
flipside query-run poll $RUN_ID --timeout 10m
flipside query-run download $RUN_ID --output results.csv

​
JSON Output for Scripting

Add --json to any command for machine-readable output: 
flipside query list --json | jq '.[] | {id, name}'