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

> Retrieve all projects in your organization with extended information

# List Projects

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

## 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 project objects with extended information.

<ResponseField name="id" type="string">
  Unique identifier (UUID)
</ResponseField>

<ResponseField name="organization_id" type="string">
  Organization UUID
</ResponseField>

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

<ResponseField name="description" type="string | null">
  Project description
</ResponseField>

<ResponseField name="start_date" type="date | null">
  Project start date (YYYY-MM-DD)
</ResponseField>

<ResponseField name="end_date" type="date | null">
  Project end date (YYYY-MM-DD)
</ResponseField>

<ResponseField name="due_date" type="date | null">
  Project due date (YYYY-MM-DD)
</ResponseField>

<ResponseField name="project_type" type="string | null">
  Project type classification

  **Possible values:** `carbon_footprint`, `custom`, `einf`, `iso_14064`, `iso_14001`, `iso_9001`, `acv`, `visualization`, `suppliers`, `logistics`
</ResponseField>

<ResponseField name="methodology" type="string | null">
  Reporting methodology

  **Possible values:** `esrs`, `gri`, `glec`
</ResponseField>

<ResponseField name="responsible_user_id" type="string">
  UUID of the user responsible for the project
</ResponseField>

<ResponseField name="responsible_user" type="object">
  Responsible user details

  <Expandable title="User Object">
    <ResponseField name="id" type="string">
      User UUID
    </ResponseField>

    <ResponseField name="email" type="string">
      User email
    </ResponseField>

    <ResponseField name="first_name" type="string | null">
      First name
    </ResponseField>

    <ResponseField name="last_name" type="string | null">
      Last name
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="parent" type="object | null">
  Parent organization info (if project is inherited from a parent org)

  <Expandable title="Parent Object">
    <ResponseField name="id" type="string">
      Parent organization UUID
    </ResponseField>

    <ResponseField name="name" type="string">
      Parent organization name
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="extended" type="object">
  Extended project metadata

  <Expandable title="Extended Object">
    <ResponseField name="number_of_files" type="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.
    </ResponseField>

    <ResponseField name="number_of_widgets" type="integer">
      Number of dashboard widgets
    </ResponseField>

    <ResponseField name="number_of_tasks" type="integer">
      Total number of tasks in the project
    </ResponseField>

    <ResponseField name="number_of_tasks_completed" type="integer">
      Number of completed tasks
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="datetime">
  Timestamp when the project was created
</ResponseField>

<ResponseField name="updated_at" type="datetime">
  Timestamp when the project was last updated
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/projects/extended" \
    -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

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

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "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"
    },
    "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"
    },
    "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

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

**Solution:** Verify your API key is valid and active. Get a new one from [Settings -> API](https://app.dcycle.io/settings/api).

### 404 Not Found

**Cause:** Organization not found

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)}")
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Project" icon="folder" href="/api-reference/projects/get">
    Get a specific project by ID
  </Card>

  <Card title="Create Project" icon="plus" href="/api-reference/projects/create">
    Create a new project
  </Card>

  <Card title="Link Entities" icon="link" href="/api-reference/projects/link-entities">
    Link entities to a project
  </Card>

  <Card title="Update Project" icon="pencil" href="/api-reference/projects/update">
    Modify project details
  </Card>
</CardGroup>