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

# Examples & Usage

> Practical examples for querying the Dema API, including organization information, definitions, and statistics data.

## Fetching Organization Information

To retrieve your organization information and available frontends:

```graphql theme={null}
query OrganizationInfoQuery {
  account {
    id
    name
    sites {
      frontendId
      name
    }
    __typename
  }
}
```

The `sites` array contains your frontend information (frontendIds), which you'll need when querying statistics data.

## Fetching Definitions

To retrieve the available [metrics](/guides/fundamentals/metrics), [dimensions](/guides/fundamentals/dimensions), and [attributionModels](/guides/fundamentals/attribution) for your organization:

```graphql theme={null}
query DefinitionsQuery {
  account {
    metrics {
      id
      label
      description
      groupId
      groupLabel
      format
      dependencies
      metricVariants {
        id
        type
        dependencies
      }
    }
    dimensions {
      id
      label
      description
      processors
      groupId
      groupLabel
      format
    }
    attributionModels {
      id
      label
      description
    }
    __typename
  }
}
```

These definitions can be used to construct your statistics queries by selecting the metrics and dimensions to use in your query.

## Fetching Statistics Data

The insights query allows you to retrieve aggregated statistics based on selected dimensions and metrics:

```graphql theme={null}
query InsightsQuery($insightsParams: InsightsInput!) {
  account {
    id
    name
    insights(params: $insightsParams) {
      data {
        dimensions
        metrics
      }
      pageInfo {
        pageSize
        offset
        hasNextPage
      }
      __typename
    }
    __typename
  }
}
```

**Example Variables**

```json theme={null}
{
  "insightsParams": {
    "frontendIds": ["DV-frontendId1", "DV-frontendId2"],
    "startDate": "2025-11-02T23:00:00.000Z",
    "endDate": "2025-12-02T22:59:59.999Z",
    "dimensions": ["channelGroup", "channel", "product"],
    "metrics": ["session:count", "session:duration", "product:inventoryValue"],
    "filter": {},
    "compareStartDate": "2025-01-05T23:00:00.000Z",
    "compareEndDate": "2025-02-02T22:59:59.999Z",
    "aggregateDimensions": ["day"]
  }
}
```

The `insightsParams` object accepts the following parameters:

* **`frontendIds`** (array of strings): List of frontend IDs to query data for
* **`startDate`** (ISO 8601 string): Start date for the data range
* **`endDate`** (ISO 8601 string): End date for the data range
* **`dimensions`** (array of strings): Dimensions to group data by (e.g., `channelGroup`, `channel`, `product`)
* **`metrics`** (array of strings): Metrics to retrieve (e.g., `session:count`, `session:duration`, `product:inventoryValue`)
* **`filter`** (object): Optional filters to apply to the data
* **`compareStartDate`** (ISO 8601 string, optional): Start date for comparison period
* **`compareEndDate`** (ISO 8601 string, optional): End date for comparison period
* **`aggregateDimensions`** (array of strings, optional): Additional dimensions for aggregation (e.g., `day`, `week`, `month`)

## Pagination

The insights endpoint supports pagination through the `pageInfo` object in the response:

* **`pageSize`**: Number of records per page
* **`offset`**: Current offset for pagination
* **`hasNextPage`**: Boolean indicating if more data is available

<Tip>
  For large datasets, we recommend using paginated queries to efficiently
  retrieve all data. Implement pagination logic in your client to fetch all
  pages when `hasNextPage` is `true`.
</Tip>

## Complete cURL Example

Here's a complete example of how to make a request using cURL:

```bash theme={null}
curl -X POST https://api.dema.ai/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "query InsightsQuery($insightsParams: InsightsInput!) { account { id name insights(params: $insightsParams) { data { dimensions metrics } pageInfo { pageSize offset hasNextPage } } } }",
    "variables": {
      "insightsParams": {
        "frontendIds": ["DV-frontendId1", "DV-frontendId2"],
        "startDate": "2025-11-02T23:00:00.000Z",
        "endDate": "2025-12-02T22:59:59.999Z",
        "dimensions": ["channelGroup"],
        "metrics": ["session:count"]
      }
    }
  }'
```

## Integration Tips

* **Error Handling**: Implement proper error handling for authentication failures, rate limits, and query errors
* **Caching**: Consider caching frequently accessed data to reduce API calls and improve performance
* **Date Formats**: Always use ISO 8601 format for dates (e.g., `2025-11-02T23:00:00.000Z`)
* **Frontend IDs**: Use the `OrganizationInfoQuery` to programmatically retrieve your frontend information (frontendIds)