> For the complete documentation index, see [llms.txt](https://documentation.kodiak.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.kodiak.finance/developers/kodiak-islands/subgraph/query-guide.md).

# Query Guide

### Introduction

This guide provides examples and best practices for querying the Kodiak Islands subgraph using GraphQL. Whether you're building a dashboard, analysis tool, or integrating with another application, these queries will help you extract the data you need.

#### Getting Started

To query the Kodiak Islands subgraph, you'll need to:

1. Know the subgraph endpoint URL ([sugraph-endpoint](https://api.goldsky.com/api/public/project_clpx84oel0al201r78jsl0r3i/subgraphs/kodiak-v3-berachain-mainnet/latest/gn))
2. Have a basic understanding of GraphQL query syntax
3. Use a GraphQL client (like Apollo Client) or make HTTP requests to the endpoint

#### Basic Query Structure

All GraphQL queries for the Kodiak Islands subgraph follow this basic structure:

```graphql
query {
  entity(where: { filter conditions }) {
    field1
    field2
    nestedEntity {
      nestedField1
      nestedField2
    }
  }
}
```

#### Common Query Examples

**1. Protocol Overview**

Get basic information about the protocol:

```graphql
query {
  kodiakIslandProtocols {
    id
    totalValueLockedUSD
    cumulativeTotalFeesUSD
    totalPoolCount
  }
}
```

**2. List All Vaults**

Retrieve all vaults with basic information:

```graphql
query {
  kodiakVaults(first: 100) {
    id
    name
    symbol
    totalValueLockedUSD
    inputToken {
      id
      symbol
      decimals
    }
    outputToken {
      id
      symbol
      decimals
    }
    manager
    managerFee
    createdTimestamp
  }
}
```

**3. Get Vault Details**

Get detailed information about a specific vault:

```graphql
query {
  kodiakVault(id: "0x1234567890abcdef1234567890abcdef12345678") {
    id
    name
    symbol
    totalValueLockedUSD
    cumulativeTotalFeesUSD
    cumulativeLpFeesUSD
    cumulativeManagerFeesUSD
    inputTokenBalance
    outputTokenSupply
    pricePerShare
    volumeUSD
    weeklyVolumeUSD
    weeklyFeesEarnedUSD
    lowerTick
    upperTick
    apr {
      averageApr
    }
    _token0 {
      symbol
    }
    _token1 {
      symbol
    }
    _token0Amount
    _token1Amount
    _token0AmountUSD
    _token1AmountUSD
  }
}
```

**4. Recent Deposits**

Query recent deposit events for a specific vault:

```graphql
query {
  kodiakDeposits(
    first: 10
    orderBy: timestamp
    orderDirection: desc
    where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
  ) {
    id
    timestamp
    from
    amount
    amountUSD
    amount0
    amount1
  }
}
```

**5. Recent Withdrawals**

Query recent withdrawal events for a specific vault:

```graphql
query {
  kodiakWithdraws(
    first: 10
    orderBy: timestamp
    orderDirection: desc
    where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
  ) {
    id
    timestamp
    to
    amount
    amountUSD
  }
}
```

**6. Daily Vault Performance**

Query daily snapshots for a vault to analyze performance over time:

```graphql
query {
  kodiakVaultDailySnapshots(
    first: 30
    orderBy: timestamp
    orderDirection: desc
    where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
  ) {
    id
    timestamp
    totalValueLockedUSD
    dailyTotalFeesUSD
    dailyLpFeesUSD
    dailyManagerFeesUSD
    volumeUSD
    volumeToken0
    volumeToken1
    apr
    pricePerShare
    lowerTick
    upperTick
  }
}
```

**7. Protocol Usage Metrics**

Query daily protocol usage metrics:

```graphql
query {
  kodiakUsageMetricsDailySnapshots(
    first: 30
    orderBy: timestamp
    orderDirection: desc
  ) {
    id
    timestamp
    dailyActiveUsers
    cumulativeUniqueUsers
    dailyTransactionCount
    dailyDepositCount
    dailyWithdrawCount
    totalPoolCount
  }
}
```

**8. Protocol Financial Metrics**

Query daily protocol financial metrics:

```graphql
query {
  kodiakFinancialsDailySnapshots(
    first: 30
    orderBy: timestamp
    orderDirection: desc
  ) {
    id
    timestamp
    totalValueLockedUSD
    dailyLpFeesUSD
    dailyManagerFeesUSD
    dailyTotalFeesUSD
  }
}
```

**9. Strategy Changes**

Track strategy changes for a specific vault:

```graphql
query {
  kodiakStrategyChanges(
    first: 20
    orderBy: timestamp
    orderDirection: desc
    where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
  ) {
    id
    timestamp
    lowerTick
    upperTick
  }
}
```

**10. Vault APR History**

Query APR history for a vault:

```graphql
query {
  kodiakVaultDailySnapshots(
    first: 90
    orderBy: timestamp
    orderDirection: desc
    where: { vault: "0x1234567890abcdef1234567890abcdef12345678" }
  ) {
    timestamp
    apr
  }
}
```

#### Filtering and Sorting

**Time-Based Filtering**

Filter snapshots within a specific time range:

```graphql
query {
  kodiakVaultDailySnapshots(
    where: {
      timestamp_gte: "1640995200" # Jan 1, 2022
      timestamp_lt: "1672531200"  # Jan 1, 2023
    }
  ) {
    timestamp
    totalValueLockedUSD
    dailyTotalFeesUSD
  }
}
```

**Value-Based Filtering**

Filter vaults by TVL:

```graphql
query {
  kodiakVaults(
    where: {
      totalValueLockedUSD_gt: "1000000" # > $1M TVL
    }
  ) {
    id
    name
    totalValueLockedUSD
  }
}
```

**Sorting Results**

Sort vaults by TVL in descending order:

```graphql
query {
  kodiakVaults(
    orderBy: totalValueLockedUSD
    orderDirection: desc
  ) {
    id
    name
    totalValueLockedUSD
  }
}
```

#### Pagination

For large result sets, use pagination with `first` and `skip`:

```graphql
query {
  kodiakVaults(
    first: 20  # Get 20 records
    skip: 20   # Skip first 20 records (for page 2)
    orderBy: totalValueLockedUSD
    orderDirection: desc
  ) {
    id
    name
    totalValueLockedUSD
  }
}
```

#### Advanced Queries

**Get User Activity Across Vaults**

Find all deposits and withdrawals for a specific user:

```graphql
query {
  deposits: kodiakDeposits(
    where: { from: "0xuser_address_here" }
  ) {
    timestamp
    vault {
      id
      name
    }
    amountUSD
  }
  withdraws: kodiakWithdraws(
    where: { to: "0xuser_address_here" }
  ) {
    timestamp
    vault {
      id
      name
    }
    amountUSD
  }
}
```

**Compare Multiple Vaults**

Compare performance metrics for multiple vaults:

```graphql
query {
  vault1: kodiakVault(id: "0xvault1_address_here") {
    id
    name
    totalValueLockedUSD
    weeklyFeesEarnedUSD
    apr {
      averageApr
    }
  }
  vault2: kodiakVault(id: "0xvault2_address_here") {
    id
    name
    totalValueLockedUSD
    weeklyFeesEarnedUSD
    apr {
      averageApr
    }
  }
}
```

#### Best Practices

1. **Query Only What You Need**: Only request the fields you actually need to minimize response size.
2. **Use Pagination**: For large collections, always use pagination to prevent timeouts.
3. **Filter Efficiently**: Apply filters at the query level rather than filtering results in your application.
4. **Optimize Sorting**: Sort at the query level for better performance.
5. **Cache Results**: GraphQL responses are highly cacheable. Implement client-side caching for better performance.
6. **Handle Time Data Correctly**: Remember that timestamps are in seconds since Unix epoch.

#### Error Handling

The subgraph may return errors for various reasons:

* Invalid query syntax
* Non-existent entities or fields
* Server timeouts for complex queries

Always implement proper error handling in your application to handle these cases gracefully.

#### Real-World Use Cases

**Building a Dashboard**

For a vault performance dashboard, you might combine protocol metrics with vault-specific data:

```graphql
query DashboardData {
  protocol: kodiakIslandProtocols(first: 1) {
    totalValueLockedUSD
    totalPoolCount
  }
  vaults: kodiakVaults(
    first: 10
    orderBy: totalValueLockedUSD
    orderDirection: desc
  ) {
    id
    name
    totalValueLockedUSD
    apr {
      averageApr
    }
  }
  recentActivity: kodiakDeposits(
    first: 5
    orderBy: timestamp
    orderDirection: desc
  ) {
    timestamp
    vault {
      name
    }
    amountUSD
  }
}
```

**Historical Analysis**

For analyzing a vault's performance over time:

```graphql
query VaultHistoricalAnalysis($vaultId: ID!, $days: Int!) {
  dailySnapshots: kodiakVaultDailySnapshots(
    first: $days
    orderBy: timestamp
    orderDirection: desc
    where: { vault: $vaultId }
  ) {
    timestamp
    totalValueLockedUSD
    dailyTotalFeesUSD
    dailyLpFeesUSD
    dailyManagerFeesUSD
    volumeUSD
    apr
  }
}
```

With these query examples and best practices, you should be well-equipped to extract valuable data from the Kodiak Islands subgraph for your applications.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.kodiak.finance/developers/kodiak-islands/subgraph/query-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.