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

# Query Examples

> Common GraphQL queries for Kleros subgraphs

# Query Examples

Common GraphQL queries for fetching data from Kleros subgraphs.

***

## V2 Core Queries (Arbitrum)

<Note>
  Always use the **decentralized network** endpoint for production queries. Get the subgraph ID from the Studio pages listed in [Subgraph Endpoints](/developers/subgraph/endpoints) and construct the URL as `https://gateway.thegraph.com/api/{API_KEY}/subgraphs/id/{SUBGRAPH_ID}`.
</Note>

### Fetch Courts

Key fields: `minStake` (in wei), `feeForJuror` (juror reward per vote), `timesPerPeriod` (array of 4 phase durations in seconds).

```graphql theme={null}
{
  courts(first: 20, orderBy: id) {
    id
    hiddenVotes
    minStake
    alpha
    feeForJuror
    jurorsForCourtJump
    timesPerPeriod
    parent { id }
    policy { policy }
    numberDisputes
    numberStakedJurors
    stakedJurors {
      id
    }
  }
}
```

### Fetch Recent Disputes

Key fields: `externalDisputeID` (your app's ID), `templateId` (links to DisputeTemplateRegistry), `ruled` (finalized), `currentRuling` (active ruling option).

```graphql theme={null}
{
  disputes(first: 10, orderBy: createdAtBlock, orderDirection: desc) {
    id
    arbitrated { id }
    court { id }

    period
    ruled
    currentRuling
    tied
    overridden
    lastPeriodChange
    nbRounds
    nbChoices
    externalDisputeID
    templateId
    rounds {
      nbVotes
      totalFeesForJurors
      drawnJurors { juror { id } }
    }
  }
}
```

### Fetch Dispute by External ID

Use `externalDisputeID` to correlate an on-chain dispute with your app's internal ID (emitted in `DisputeRequest`):

```graphql theme={null}
query GetDisputeByExternalID($externalId: BigInt!) {
  disputes(where: { externalDisputeID: $externalId }) {
    id
    period
    ruled
    currentRuling
    tied
    templateId
  }
}
```

### Fetch Juror Stakes for a Specific Address

```graphql theme={null}
{
  jurorTokensPerCourts(where: { juror: "0xYOUR_ADDRESS_LOWERCASE" }) {
    court { id }
    staked
    locked
  }
}
```

### Fetch Juror's Active Draws

```graphql theme={null}
query GetJurorDraws($juror: String!) {
  draws(where: { juror: $juror, vote_not: null }, first: 20) {
    dispute { id period currentRuling }
    round { id nbVotes }
    vote { choice }
  }
}
```

***

## Curate Queries (V1)

### Fetch Registered Items from a Light Curate List

```graphql theme={null}
{
  litems(
    first: 10
    where: {
      status: Registered
      registryAddress: "0xYOUR_LIST_ADDRESS_LOWERCASE"
    }
    orderBy: latestRequestResolutionTime
    orderDirection: desc
  ) {
    itemID
    data
    props {
      type
      label
      description
      value
    }
  }
}
```

### Fetch Items in Challenge Period

```graphql theme={null}
{
  litems(
    first: 10
    where: {
      status_in: [RegistrationRequested, ClearingRequested]
      registryAddress: "0xYOUR_LIST_ADDRESS_LOWERCASE"
      disputed: false
    }
    orderBy: latestRequestSubmissionTime
    orderDirection: asc
  ) {
    itemID
    status
    props {
      label
      value
    }
    requests(first: 1, orderBy: submissionTime, orderDirection: desc) {
      submissionTime
      requester
    }
  }
}
```

### Fetch Item Details with Request History

```graphql theme={null}
query ItemDetails($id: ID!) {
  item(id: $id) {
    data
    requests(orderBy: submissionTime, orderDirection: desc) {
      requestType
      disputed
      disputeID
      submissionTime
      resolved
      requester
      challenger
      rounds(orderBy: creationTime, orderDirection: desc) {
        appealPeriodStart
        appealPeriodEnd
        ruling
        hasPaidRequester
        hasPaidChallenger
      }
    }
  }
}
```

Item IDs in the subgraph use the format `<itemID>@<listAddress>`:

```typescript theme={null}
const compoundId = `${itemID}@${tcrAddress.toLowerCase()}`;
const result = useQuery(ITEM_DETAILS_QUERY, { variables: { id: compoundId } });
```

***

## Address Tag Registries (Gnosis Chain)

Batched query to fetch address tags from the three Kleros address tag registries on Gnosis Chain:

```graphql theme={null}
{
  contractDomainTags: litems(
    where: {
      status_in: [Registered, ClearingRequested]
      registryAddress: "0x CONTRACT_DOMAIN_TAG_REGISTRY"
    }
    first: 1000
  ) {
    props { label value }
  }
  addressTags: litems(
    where: {
      status_in: [Registered, ClearingRequested]
      registryAddress: "0x ADDRESS_TAG_REGISTRY"
    }
    first: 1000
  ) {
    props { label value }
  }
}
```

Endpoint: `https://thegraph.com/hosted-service/subgraph/kleros/legacy-curate-xdai`

***

## Proof of Humanity

### Check Registration Status

```graphql theme={null}
{
  submission(id: "0xADDRESS_LOWERCASE") {
    registered
    name
    creationTime
    status
    requests(first: 1, orderBy: creationTime, orderDirection: desc) {
      evidence {
        URI
      }
    }
  }
}
```

Alternatively, call `isRegistered(address)` directly on the PoH contract at `0xC5E9dDebb09Cd64DfaCab4011A0D5cEDaf7c9BDb`.

***

## Tips

* Addresses must be **lowercase** in all queries. The subgraph stores them as bytes and does not understand checksummed addresses.
* Items with status `ClearingRequested` are still registered until the removal request is finalized. Include them when fetching "active" items.
* The Graph hosted service has a **1000 item limit** per query. For registries with more items, paginate using `skip` or `id_gt`.
* Light Curate entities are prefixed with `l` (e.g., `litems`, `lrequests`). Classic Curate uses unprefixed entities (`items`, `requests`).

***

## Further Reading

<CardGroup cols={2}>
  <Card title="Subgraph Endpoints" icon="link" href="/developers/subgraph/endpoints">
    Full list of subgraph URLs
  </Card>

  <Card title="Light Curate Integration" icon="list-check" href="/developers/legacy/light-curate">
    Full Light Curate developer guide
  </Card>
</CardGroup>