> ## 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 Response Sets

> List all survey submissions in a campaign with values and attachments

# List Response Sets

Retrieve a paginated list of all survey submissions (response sets) in a campaign. Each response set includes the submitted KPI values, file attachments, and recipient information.

## 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>

### Path Parameters

<ParamField path="dataset_id" type="string" required>
  UUID of the dataset
</ParamField>

<ParamField path="campaign_id" type="string" required>
  UUID of the campaign
</ParamField>

### Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number (min 1)
</ParamField>

<ParamField query="size" type="integer" default="20">
  Items per page (1–100)
</ParamField>

## Response

<ResponseField name="items" type="array[object]">
  List of response sets
</ResponseField>

<ResponseField name="items[].id" type="string">
  Response set UUID
</ResponseField>

<ResponseField name="items[].campaign_assignment_id" type="string">
  UUID of the campaign assignment this response belongs to
</ResponseField>

<ResponseField name="items[].submitted_at" type="string">
  ISO 8601 timestamp of submission
</ResponseField>

<ResponseField name="items[].submitter_email" type="string | null">
  Email of the person who submitted
</ResponseField>

<ResponseField name="items[].data_owner_email" type="string">
  Email of the assigned data owner
</ResponseField>

<ResponseField name="items[].organization_name" type="string">
  Organization name of the recipient
</ResponseField>

<ResponseField name="items[].facility_name" type="string | null">
  Facility name, if the assignment is facility-scoped
</ResponseField>

<ResponseField name="items[].values" type="array[object]">
  Submitted KPI values
</ResponseField>

<ResponseField name="items[].values[].kpi_id" type="string">
  KPI UUID
</ResponseField>

<ResponseField name="items[].values[].kpi_name" type="string">
  KPI display name
</ResponseField>

<ResponseField name="items[].values[].value_numeric" type="number | null">
  Numeric value (for NUMBER/PERCENTAGE KPIs)
</ResponseField>

<ResponseField name="items[].values[].value_text" type="string | null">
  Text value (for TEXT/SELECT KPIs)
</ResponseField>

<ResponseField name="items[].values[].value_date" type="string | null">
  Date value (for DATE KPIs)
</ResponseField>

<ResponseField name="items[].attachments" type="array[object]">
  File attachments included with the submission
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of response sets
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.dcycle.io/v1/custom-kpi-datasets/${DATASET_ID}/campaigns/${CAMPAIGN_ID}/response-sets?page=1&size=10" \
    -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

  response = requests.get(
      f"https://api.dcycle.io/v1/custom-kpi-datasets/{os.getenv('DATASET_ID')}"
      f"/campaigns/{os.getenv('CAMPAIGN_ID')}/response-sets",
      headers={
          "x-api-key": os.getenv("DCYCLE_API_KEY"),
          "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
      },
      params={"page": 1, "size": 10},
  )

  data = response.json()
  print(f"{data['total']} total submissions")
  for rs in data["items"]:
      print(f"  {rs['data_owner_email']} ({rs['organization_name']}): {len(rs['values'])} values")
  ```

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

  const response = await axios.get(
    `https://api.dcycle.io/v1/custom-kpi-datasets/${process.env.DATASET_ID}/campaigns/${process.env.CAMPAIGN_ID}/response-sets`,
    {
      headers: {
        'x-api-key': process.env.DCYCLE_API_KEY,
        'x-organization-id': process.env.DCYCLE_ORG_ID,
      },
      params: { page: 1, size: 10 },
    }
  );

  console.log(`${response.data.total} total submissions`);
  response.data.items.forEach(rs =>
    console.log(`  ${rs.data_owner_email} (${rs.organization_name}): ${rs.values.length} values`)
  );
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "response-set-uuid",
      "campaign_assignment_id": "assignment-uuid",
      "submitted_at": "2025-03-15T14:30:00Z",
      "submitter_email": "ana@acme.com",
      "submitter_user_id": "user-uuid",
      "data_owner_email": "ana@acme.com",
      "organization_name": "Acme Corp",
      "facility_name": "Madrid Office",
      "values": [
        {
          "kpi_id": "kpi-uuid-1",
          "kpi_name": "Water consumption",
          "kpi_unit": "m³",
          "value_numeric": 1250.5,
          "value_text": null,
          "value_date": null
        },
        {
          "kpi_id": "kpi-uuid-2",
          "kpi_name": "Recycling policy",
          "kpi_unit": null,
          "value_numeric": null,
          "value_text": "Yes",
          "value_date": null
        }
      ],
      "attachments": [
        {
          "file_id": "file-uuid",
          "file_name": "water-bill-q1.pdf",
          "file_url": "https://..."
        }
      ]
    }
  ],
  "total": 15
}
```

## 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"}
```

### 404 Not Found

**Cause:** The dataset or campaign does not exist or belongs to another organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Not Found"}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Campaign Values" icon="table" href="/api-reference/custom-kpi/list-campaign-values">
    View aggregated values across all recipients
  </Card>

  <Card title="Get Campaign" icon="bullhorn" href="/api-reference/custom-kpi/get-campaign">
    View campaign details
  </Card>
</CardGroup>