List Response Sets

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": {},
  "items[].id": "<string>",
  "items[].campaign_assignment_id": "<string>",
  "items[].submitted_at": "<string>",
  "items[].submitter_email": {},
  "items[].data_owner_email": "<string>",
  "items[].organization_name": "<string>",
  "items[].facility_name": {},
  "items[].values": {},
  "items[].values[].kpi_id": "<string>",
  "items[].values[].kpi_name": "<string>",
  "items[].values[].value_numeric": {},
  "items[].values[].value_text": {},
  "items[].values[].value_date": {},
  "items[].attachments": {},
  "total": 123
}

GET

custom-kpi-datasets

{dataset_id}

campaigns

{campaign_id}

response-sets

List Response Sets

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/campaigns/{campaign_id}/response-sets \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "items": {},
  "items[].id": "<string>",
  "items[].campaign_assignment_id": "<string>",
  "items[].submitted_at": "<string>",
  "items[].submitter_email": {},
  "items[].data_owner_email": "<string>",
  "items[].organization_name": "<string>",
  "items[].facility_name": {},
  "items[].values": {},
  "items[].values[].kpi_id": "<string>",
  "items[].values[].kpi_name": "<string>",
  "items[].values[].value_numeric": {},
  "items[].values[].value_text": {},
  "items[].values[].value_date": {},
  "items[].attachments": {},
  "total": 123
}

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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

string

required

UUID of the dataset

string

required

UUID of the campaign

Query Parameters

integer

default:"1"

Page number (min 1)

integer

default:"20"

Items per page (1–100)

Response

array[object]

List of response sets

string

Response set UUID

string

UUID of the campaign assignment this response belongs to

string

ISO 8601 timestamp of submission

string | null

Email of the person who submitted

string

Email of the assigned data owner

string

Organization name of the recipient

string | null

Facility name, if the assignment is facility-scoped

array[object]

Submitted KPI values

string

KPI UUID

string

KPI display name

number | null

Numeric value (for NUMBER/PERCENTAGE KPIs)

string | null

Text value (for TEXT/SELECT KPIs)

string | null

Date value (for DATE KPIs)

array[object]

File attachments included with the submission

integer

Total number of response sets

Example

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

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")

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`)
);

Successful Response

{
  "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

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

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

{"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

{"detail": "Not Found"}

List Campaign Values

View aggregated values across all recipients

Get Campaign

View campaign details

​List Response Sets

​Request

​Headers

​Path Parameters

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

List Campaign Values

Get Campaign

List Response Sets

Request

Headers

Path Parameters

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints