> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flipsidecrypto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with data & results

> Validate, download, and manipulate data from FlipsideAI analyses

FlipsideAI is fully transparent. Every query, every calculation, every data point is accessible for
validation, download, and further analysis.

## Understanding Flipside Data boxes

When FlipsideAI runs a query, results appear in **Flipside Data boxes**—expandable containers that
show:

<Steps>
  <Step title="Query preview">Summary of the query that was run</Step>
  <Step title="Results table">Data returned by the query</Step>
  <Step title="Full SQL">Complete, executable SQL query</Step>
  <Step title="Download option">Export results as CSV</Step>
</Steps>

### Expanding data boxes

<AccordionGroup>
  <Accordion title="View the query" icon="code">
    Click the data box to expand and see:

    * Full SQL code
    * Tables queried
    * Filters applied
    * Joins and aggregations

    Use this to verify FlipsideAI's approach.
  </Accordion>

  <Accordion title="Inspect results" icon="table">
    See the raw data:

    * All columns returned
    * Row-by-row detail
    * Data types and formatting

    Cross-check against your expectations.
  </Accordion>

  <Accordion title="Check execution details" icon="info-circle">
    See metadata:

    * Execution time
    * Rows returned
    * Data freshness (when the underlying tables were last updated)
  </Accordion>
</AccordionGroup>

## Validating results

Always validate before trusting the numbers, especially for high-stakes decisions.

### Sanity checks

<Tabs>
  <Tab title="Compare to known benchmarks">
    Cross-reference with external sources:

    * **TVL**: Check against DeFiLlama, DefiPulse
    * **Prices**: Verify with CoinGecko, CoinMarketCap
    * **Volumes**: Compare to protocol dashboards or Dune Analytics

    If numbers diverge significantly, investigate why.
  </Tab>

  <Tab title="Inspect the SQL">
    Expand the query and check: - Are the right tables being used? - Are filters correct (date ranges,
    chains, addresses)? - Are joins valid (e.g., joining on the right keys)? - Are aggregations
    appropriate (SUM vs AVG vs COUNT)?
  </Tab>

  <Tab title="Ask for validation">
    Tell FlipsideAI to double-check:

    * "Validate these results using an alternative approach"
    * "Cross-check this against \[external source]"
    * "Why might this number be different from \[expected value]?"

    FlipsideAI can recompute using different methods.
  </Tab>

  <Tab title="Test with known cases">
    Run a query where you already know the answer:

    * "Show me USDC transfers on 2024-01-15" (pick a date you can verify elsewhere)
    * Compare results to confirm the methodology is sound
  </Tab>
</Tabs>

### Common data quality issues

<Warning>
  Watch out for: - **Incomplete data**: Some chains or protocols may have data gaps - **Token vs USD
  amounts**: Verify whether values are in token units or USD - **Duplicate counting**: In complex
  joins, rows might be double-counted - **Stale data**: Check when tables were last updated
  (especially for "current" metrics)
</Warning>

If you spot an issue, point it out:

```text theme={null}
"This TVL seems too low. Can you check if LP tokens are being counted correctly?"
```

## Downloading data

### CSV export

Every Flipside Data box has a download button:

<Steps>
  <Step title="Expand the data box">Click to open the query results</Step>
  <Step title="Click the download icon">Usually in the top-right of the data box</Step>
  <Step title="Save the CSV">File downloads with query results</Step>
</Steps>

### What you get

* All columns from the query
* All rows (up to query limits)
* Column headers
* Raw data (no visualizations, just the numbers)

### Use cases for CSV export

* **Further analysis**: Import into Excel, Python, R, or your tool of choice
* **Archiving**: Save snapshots for historical comparison
* **Sharing with non-technical stakeholders**: Send raw data alongside visualizations
* **Custom visualizations**: Build your own charts with the data

## Running queries directly

Already know SQL? Skip the chat and run queries directly.

### Paste SQL into chat

```sql theme={null}
SELECT
  DATE_TRUNC('day', block_timestamp) AS date,
  COUNT(DISTINCT from_address) AS unique_users,
  SUM(amount_usd) AS volume_usd
FROM ethereum.defi.ez_dex_swaps
WHERE platform = 'uniswap-v3'
  AND block_timestamp >= '2024-01-01'
GROUP BY 1
ORDER BY 1
```

Paste this into chat, and FlipsideAI will:

1. Execute the query
2. Return results
3. Offer to summarize, visualize, or analyze further

### Why run queries directly?

* **Precision**: You control exactly what data is retrieved
* **Speed**: Skip the "figure out what I want" step
* **Reproducibility**: Same query → same results every time
* **Learning**: See how FlipsideAI would structure a query, then tweak it

## Uploading your own data

Upload CSVs to combine external data with Flipside's blockchain data.

### How to upload

<Steps>
  <Step title="Click the upload icon">In the chat interface, look for the file upload option</Step>
  <Step title="Select your CSV">Upload a well-formatted CSV file</Step>

  <Step title="Describe the data">
    Tell FlipsideAI what the CSV contains: - "This is a list of addresses I want to analyze" -
    "These are token balances from an external source"
  </Step>

  <Step title="Ask your question">
    "Analyze these addresses for airdrop farmer behavior" "Join this with Flipside data to track
    user activity"
  </Step>
</Steps>

### Privacy

* **Uploads are private**: Your CSV data stays private to you
* **Not shared**: Other users cannot see your uploaded data
* **Temporary**: Files are not stored permanently (only for the session)

### Use cases

<AccordionGroup>
  <Accordion title="Address lists" icon="list">
    Upload a list of addresses to:

    * Analyze their onchain behavior
    * Track token holdings over time
    * Identify patterns or anomalies
  </Accordion>

  <Accordion title="Custom cohorts" icon="users">
    Define your own user segments: - Upload a CSV of "power users" based on off-chain criteria -
    Compare their behavior to the broader population
  </Accordion>

  <Accordion title="External benchmarks" icon="chart-line">
    Upload data from other sources: - Compare Flipside data to your internal metrics - Validate
    consistency across data providers
  </Accordion>

  <Accordion title="Airdrop targeting" icon="parachute-box">
    Upload recipient lists:

    * Analyze their wallet activity
    * Check for sybil behavior or wash trading
    * Score addresses based on quality metrics
  </Accordion>
</AccordionGroup>

## Handling errors or odd results

Sometimes queries fail or return unexpected data. Here's how to handle it.

### FlipsideAI auto-retries

When a query fails, FlipsideAI automatically:

1. Identifies the error
2. Adjusts the query
3. Retries

You'll see: "Retrying with updated query..."

### Persistent errors

If retries don't work, try:

<AccordionGroup>
  <Accordion title="Ask to try a different table" icon="table">
    ```text theme={null}
    "This query failed. Can you try using a different table?"
    ```

    Sometimes alternative tables have the same data with different schema.
  </Accordion>

  <Accordion title="Recalc token vs USD" icon="dollar-sign">
    ```text theme={null}
    "These numbers seem off. Are you using token amounts or USD amounts?"
    ```

    Token/USD confusion is a common issue—clarify the units.
  </Accordion>

  <Accordion title="Simplify the query" icon="minimize">
    ```text theme={null}
    "This query is too complex and timing out. Can you break it into steps?"
    ```

    Large queries can be split into smaller, faster queries.
  </Accordion>

  <Accordion title="Walk step-by-step" icon="shoe-prints">
    ```text theme={null}
    "Let's do this in steps:
    1. First, show me total volume
    2. Then, break it down by protocol
    3. Finally, add the time series"
    ```

    Sequential queries are more reliable than one big query.
  </Accordion>
</AccordionGroup>

## Pro tips

<AccordionGroup>
  <Accordion title="Export early, export often" icon="download">
    Don't wait until the end of a long analysis to export data. Download intermediate results as you go—especially if the chat is getting long and might hit context limits.
  </Accordion>

  <Accordion title="Use CSVs for reproducible reports" icon="file-csv">
    Download data from FlipsideAI, then build your own charts/reports in tools you control. This is
    useful for: - Client deliverables - Recurring reports (monthly, quarterly) - Custom dashboards
  </Accordion>

  <Accordion title="Ask for data dictionary" icon="book">
    If you're unfamiliar with a table:

    ```text theme={null}
    "What columns are in the ethereum.defi.ez_dex_swaps table?"
    ```

    FlipsideAI can explain table schemas.
  </Accordion>

  <Accordion title="Combine uploaded data with live query" icon="bolt">
    Upload a list of addresses, then:

    ```text theme={null}
    "Use live query to get the current USDC balance for each address in my CSV"
    ```

    This blends external data with real-time blockchain state.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Reports & Artifacts" icon="file-chart-column" href="/flipsideai/reports-and-artifacts">
    Learn how to create shareable reports and artifacts
  </Card>

  <Card title="Sharing & exporting" icon="share-nodes" href="/flipsideai/sharing">
    Publish and share your analyses
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/flipsideai/troubleshooting">
    Fix common data and query issues
  </Card>

  <Card title="Analysis modes" icon="gears" href="/flipsideai/analysis-modes">
    Understand how different modes handle data
  </Card>
</CardGroup>