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

# List Datasets

> List all custom KPI datasets for your organization

# List Datasets

Retrieve all custom KPI datasets belonging to your organization. Each dataset defines a collection of KPI questions that can be assigned to data owners via campaigns.

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

## Response

Returns an array of dataset objects with HTTP 200.

<ResponseField name="id" type="string">
  UUID of the dataset
</ResponseField>

<ResponseField name="organization_id" type="string">
  UUID of the owning organization
</ResponseField>

<ResponseField name="name" type="string">
  Dataset name
</ResponseField>

<ResponseField name="description" type="string">
  Dataset description (nullable)
</ResponseField>

<ResponseField name="created_by" type="string">
  UUID of the user who created the dataset (nullable)
</ResponseField>

<ResponseField name="created_at" type="datetime">
  ISO 8601 timestamp
</ResponseField>

<ResponseField name="updated_at" type="datetime | null">
  ISO 8601 timestamp (nullable)
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/custom-kpi-datasets" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  headers = {
      "x-api-key": os.getenv("DCYCLE_API_KEY"),
      "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
  }

  response = requests.get(
      "https://api.dcycle.io/v1/custom-kpi-datasets",
      headers=headers,
  )

  datasets = response.json()
  for ds in datasets:
      print(f"{ds['name']} — {len(ds.get('kpis', []))} KPIs")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const headers = {
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID,
  };

  axios.get('https://api.dcycle.io/v1/custom-kpi-datasets', { headers })
    .then(response => {
      response.data.forEach(ds => console.log(`${ds.name}`));
    });
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
    "name": "Water Usage Survey",
    "description": "Monthly water consumption across facilities",
    "created_by": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "updated_by": null,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": null
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
    "name": "Waste Tracking",
    "description": null,
    "created_by": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "updated_by": null,
    "created_at": "2025-02-01T09:00:00Z",
    "updated_at": null
  }
]
```

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

**Cause:** The authenticated user is not a member of the organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Dataset" icon="plus" href="/api-reference/custom-kpi/create-dataset">
    Create a new dataset with KPI definitions
  </Card>

  <Card title="Get Dataset" icon="magnifying-glass" href="/api-reference/custom-kpi/get-dataset">
    View a dataset with its KPIs
  </Card>
</CardGroup>