List Projects - Dcycle Platform Docs

List Projects

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

fetch('https://api.dcycle.io/v1/projects/extended', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/projects/extended"

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

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

print(response.text)

{
  "id": "<string>",
  "organization_id": "<string>",
  "name": "<string>",
  "description": {},
  "start_date": {},
  "end_date": {},
  "due_date": {},
  "project_type": {},
  "methodology": {},
  "responsible_user_id": "<string>",
  "responsible_user": {
    "id": "<string>",
    "email": "<string>",
    "first_name": {},
    "last_name": {},
    "profile_img_url": {}
  },
  "parent": {
    "id": "<string>",
    "name": "<string>"
  },
  "extended": {
    "number_of_files": 123,
    "number_of_widgets": 123,
    "number_of_tasks": 123,
    "number_of_tasks_completed": 123
  },
  "created_at": {},
  "updated_at": {}
}

GET

projects

extended

List Projects

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

fetch('https://api.dcycle.io/v1/projects/extended', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/projects/extended"

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

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

print(response.text)

{
  "id": "<string>",
  "organization_id": "<string>",
  "name": "<string>",
  "description": {},
  "start_date": {},
  "end_date": {},
  "due_date": {},
  "project_type": {},
  "methodology": {},
  "responsible_user_id": "<string>",
  "responsible_user": {
    "id": "<string>",
    "email": "<string>",
    "first_name": {},
    "last_name": {},
    "profile_img_url": {}
  },
  "parent": {
    "id": "<string>",
    "name": "<string>"
  },
  "extended": {
    "number_of_files": 123,
    "number_of_widgets": 123,
    "number_of_tasks": 123,
    "number_of_tasks_completed": 123
  },
  "created_at": {},
  "updated_at": {}
}

← Projects API Retrieve all projects in your organization including extended metadata such as file counts, widget counts, task counts, and task completion progress.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

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

Query Parameters

array[string]

Filter by framework(s)

array[string]

Filter by responsible user UUID(s)

array[string]

Filter by parent organization UUID(s)

date

Filter projects with start date >= value (YYYY-MM-DD)

date

Filter projects with start date <= value (YYYY-MM-DD)

date

Filter projects with end date >= value (YYYY-MM-DD)

date

Filter projects with end date <= value (YYYY-MM-DD)

date

Filter projects with due date >= value (YYYY-MM-DD)

date

Filter projects with due date <= value (YYYY-MM-DD)

Response

Returns an array of project objects with extended information.

string

Unique identifier (UUID)

string

Organization UUID

string

Project name

string | null

Project description

date | null

Project start date (YYYY-MM-DD)

date | null

Project end date (YYYY-MM-DD)

date | null

Project due date (YYYY-MM-DD)

string | null

Project type classificationPossible values: carbon_footprint, custom, einf, iso_14064, iso_14001, iso_9001, acv, visualization, suppliers, logistics

string | null

Reporting methodologyPossible values: esrs, gri, glec

string

UUID of the user responsible for the project

object

Responsible user details

Show User Object

string

User UUID

string

User email

string | null

First name

string | null

Last name

string | null

Profile image URL

object | null

Parent organization info (if project is inherited from a parent org)

Show Parent Object

string

Parent organization UUID

string

Parent organization name

object

Extended project metadata

Show Extended Object

integer

Number of active raw files attached to the project. Matches what the project’s Files page shows — soft-deleted files and non-raw artifacts (e.g. generated downloads) are excluded.

integer

Number of dashboard widgets

integer

Total number of tasks in the project

integer

Number of completed tasks

datetime

Timestamp when the project was created

datetime | null

Timestamp when the project was last updated

Example

curl -X GET "https://api.dcycle.io/v1/projects/extended" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id
}

response = requests.get(
    "https://api.dcycle.io/v1/projects/extended",
    headers=headers
)

projects = response.json()
for project in projects:
    ext = project["extended"]
    print(f"{project['name']}: {ext['number_of_tasks_completed']}/{ext['number_of_tasks']} tasks done")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId
};

axios.get(
  'https://api.dcycle.io/v1/projects/extended',
  { headers }
)
.then(response => {
  response.data.forEach(project => {
    const ext = project.extended;
    console.log(`${project.name}: ${ext.number_of_tasks_completed}/${ext.number_of_tasks} tasks done`);
  });
})
.catch(error => console.error(error));

Successful Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
    "name": "Carbon Footprint 2024",
    "description": "Annual carbon footprint calculation for FY2024",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "due_date": "2025-03-31",
    "project_type": "carbon_footprint",
    "methodology": "gri",
    "responsible_user_id": "user-uuid-001",
    "responsible_user": {
      "id": "user-uuid-001",
      "email": "maria@company.com",
      "first_name": "Maria",
      "last_name": "Garcia",
      "profile_img_url": null
    },
    "parent": null,
    "extended": {
      "number_of_files": 12,
      "number_of_widgets": 5,
      "number_of_tasks": 24,
      "number_of_tasks_completed": 18
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-06-20T14:45:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
    "name": "ISO 14064 Certification",
    "description": "Prepare ISO 14064-1 verification",
    "start_date": "2024-03-01",
    "end_date": "2024-09-30",
    "due_date": "2024-10-15",
    "project_type": "iso_14064",
    "methodology": null,
    "responsible_user_id": "user-uuid-002",
    "responsible_user": {
      "id": "user-uuid-002",
      "email": "carlos@company.com",
      "first_name": "Carlos",
      "last_name": "Lopez",
      "profile_img_url": null
    },
    "parent": null,
    "extended": {
      "number_of_files": 8,
      "number_of_widgets": 3,
      "number_of_tasks": 15,
      "number_of_tasks_completed": 15
    },
    "created_at": "2024-03-01T09:00:00Z",
    "updated_at": "2024-09-28T16:30:00Z"
  }
]

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

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

Solution: Verify your API key is valid and active. Get a new one from Settings -> API.

404 Not Found

Cause: Organization not found

{
  "code": "ORGANIZATION_NOT_FOUND",
  "detail": "Organization with id=UUID('...') not found"
}

Solution: Verify that the x-organization-id header contains a valid organization UUID.

Use Cases

Track Project Progress

Monitor task completion across all projects:

def get_project_progress():
    """Get progress summary for all projects"""
    response = requests.get(
        "https://api.dcycle.io/v1/projects/extended",
        headers=headers
    )

    for project in response.json():
        ext = project["extended"]
        total = ext["number_of_tasks"]
        done = ext["number_of_tasks_completed"]
        pct = (done / total * 100) if total > 0 else 0
        print(f"{project['name']}: {pct:.0f}% ({done}/{total} tasks)")

get_project_progress()

Filter Projects by Type

Find all carbon footprint projects:

def get_projects_by_type(project_type):
    """Get projects filtered by type"""
    response = requests.get(
        "https://api.dcycle.io/v1/projects/extended",
        headers=headers
    )

    return [p for p in response.json() if p["project_type"] == project_type]

cf_projects = get_projects_by_type("carbon_footprint")
print(f"Carbon footprint projects: {len(cf_projects)}")

Get Project

Get a specific project by ID

Create Project

Create a new project

Link Entities

Link entities to a project

Update Project

Modify project details

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​Use Cases

​Track Project Progress

​Filter Projects by Type

​Related Endpoints

Get Project

Create Project

Link Entities

Update Project

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

Use Cases

Track Project Progress

Filter Projects by Type

Related Endpoints