# List an organization's projects you can read

GET`/v1/projects/{org_id}`[Token scope: `projects:read`](https://developers.tasksmate.indrasol.com/guides/authentication/#scopes)[paginated list](https://developers.tasksmate.indrasol.com/guides/pagination-and-filters/)

Request

**curl**


```bash
curl -X GET "https://tasksmate-fdfsarhnf5gacfb7.eastus-01.azurewebsites.net/v1/projects/<org_id>" \
  -H "Authorization: Bearer $TASKSMATE_TOKEN"
```

**Python**


```python
from tasksmate import TasksMate

tm = TasksMate()  # reads TASKSMATE_TOKEN
for item in tm.projects.list("<org_id>"):  # follows next_cursor through every page
    print(item)
```

**tm**


```bash
tm projects list --org O0020
```

Response 200

```json
{
  "data": [
    {
      "org_id": "a1b2c3d4-5678-1234-9abc-def012345678",
      "name": "Website Redesign",
      "description": "Redesign the company website.",
      "metadata": {
        "budget": 10000
      },
      "status": "not_started",
      "priority": "high",
      "start_date": "2024-07-01",
      "end_date": "2024-12-31",
      "created_by": "string",
      "updated_by": "string",
      "is_active": true,
      "delete_reason": "string",
      "owner": "string",
      "team_members": [
        "string"
      ],
      "visibility": "public",
      "team_id": "string",
      "project_id": "P00001",
      "created_at": "2026-09-25T12:00:00Z",
      "updated_at": "2026-09-25T12:00:00Z",
      "tasks_total": 25,
      "tasks_completed": 15,
      "progress_percent": 60,
      "leads": [
        {
          "user_id": "string",
          "username": "string",
          "assigned_by": "string",
          "assigned_at": "2026-09-25T12:00:00Z"
        }
      ],
      "position": 0
    }
  ],
  "next_cursor": "string"
}
```

The organization’s projects, paginated as `{data, next_cursor}`.

-   `show_all=true` returns every project you can read: public projects, the projects you are a member of, and — for org owners and admins — all of them. Private projects you are not a member of never appear.
-   `show_all=false` returns only the projects you are a member of.
-   `filter[status]`, `filter[priority]`, `filter[team]` (team ids) and `filter[project]` (project ids) narrow the list.
-   `filter[search]` matches the name, description or id (case-insensitive substring).
-   `filter[start_after]` / `filter[start_before]` (`YYYY-MM-DD`, inclusive) bound the start date — the creation date when a project has none.

## Authorizations

-   **[bearerAuth](https://developers.tasksmate.indrasol.com/reference/#bearerauth)**
-   **[TasksMateToken](https://developers.tasksmate.indrasol.com/reference/#tasksmatetoken)**

## Parameters

### Path Parameters

**org\_id**

required

_Org Id_

string

### Query Parameters

**show\_all**

_Show All_

boolean

default: true

**limit**

_Limit_

Page size; default 1000, capped at 1000. Filters: `filter[status]`, `filter[priority]`, `filter[team]`, `filter[project]`, `filter[search]`, `filter[start_after]`, `filter[start_before]` (comma-separated values are OR-ed).

integer

default: 1000 \>= 1

Page size; default 1000, capped at 1000. Filters: `filter[status]`, `filter[priority]`, `filter[team]`, `filter[project]`, `filter[search]`, `filter[start_after]`, `filter[start_before]` (comma-separated values are OR-ed).

**cursor**

Any of:

**string**


string

**null**


null

The previous page’s `next_cursor`, echoed back verbatim

**sort\_by**

Any of:

**string**


string

**null**


null

One of: name, position, status, priority, start\_date, end\_date, created\_at, updated\_at, progress\_percent, project\_id, visibility. Default: the list’s natural order.

**sort\_order**

_Sort Order_

`asc` or `desc`

string

default: asc

`asc` or `desc`

### Header Parameters

**If-None-Match**

string

An `ETag` you hold; unchanged → 304 with no body.

## Responses

### 200

Successful Response

application/json

_Page\[ProjectCard\]_

Returned by `projects.list` and `views.rows`.

object

**data**

required

_Data_

Array<object>

_ProjectCard_

Simplified project representation for dashboard cards.

object

**org\_id**

required

_Org Id_

Organization ID (UUID)

string

**name**

required

_Name_

Project name

string

**description**

Any of:

**string**


string

**null**


null

**metadata**

Any of:

**object**
object

**_key_**

additional properties

any

**null**


null

**status**

Any of:

**ProjectStatusEnum**
_ProjectStatusEnum_

Project status enum

string

Allowed values: planning in\_progress not\_started active completed archived on\_hold blocked paused

**null**


null

**priority**

Any of:

**PriorityEnum**
_PriorityEnum_

Priority enum for projects and tasks

string

Allowed values: high medium low none critical

**null**


null

**start\_date**

Any of:

**string**


string format: date

**null**


null

**end\_date**

Any of:

**string**


string format: date

**null**


null

**created\_by**

Any of:

**string**


string

**null**


null

**updated\_by**

Any of:

**string**


string

**null**


null

**is\_active**

Any of:

**boolean**


boolean

**null**


null

**delete\_reason**

Any of:

**string**


string

**null**


null

**owner**

Any of:

**string**


string

**null**


null

**team\_members**

Any of:

**Array<string>**


Array<string>

**null**


null

**visibility**

Any of:

**ProjectVisibilityEnum**
_ProjectVisibilityEnum_

Who can see a project: `public` — every member of the organization; `private` — the project’s members and org admins. Also the organization’s default for new projects.

string

Allowed values: public private

**null**


null

**team\_id**

Any of:

**string**


string

**null**


null

**project\_id**

required

_Project Id_

Project ID

string

**created\_at**

Any of:

**string**


string format: date-time

**null**


null

**updated\_at**

Any of:

**string**


string format: date-time

**null**


null

**tasks\_total**

required

_Tasks Total_

Total number of tasks in the project

integer

**tasks\_completed**

required

_Tasks Completed_

Number of completed tasks

integer

**progress\_percent**

required

_Progress Percent_

Project completion percentage, 0–100.

number

**leads**

_Leads_

The project’s leads; optional, usually empty.

Array<object>

_ProjectLeadOut_

One lead of a project: who, who set them, and when. A lead is distinct from the owner — the owner administers the project, a lead is accountable for delivering it.

object

**user\_id**

required

_User Id_

string

**username**

Any of:

**string**


string

**null**


null

**assigned\_by**

Any of:

**string**


string

**null**


null

**assigned\_at**

Any of:

**string**


string format: date-time

**null**


null

**position**

_Position_

The project’s place in the organization’s manual order. Lists sort by position, then name.

integer

0

**next\_cursor**

Any of:

**string**


string

**null**


null

Example

```json
{
  "data": [
    {
      "org_id": "a1b2c3d4-5678-1234-9abc-def012345678",
      "name": "Website Redesign",
      "description": "Redesign the company website.",
      "metadata": {
        "budget": 10000
      },
      "status": "not_started",
      "priority": "high",
      "start_date": "2024-07-01",
      "end_date": "2024-12-31",
      "created_by": "string",
      "updated_by": "string",
      "is_active": true,
      "delete_reason": "string",
      "owner": "string",
      "team_members": [
        "string"
      ],
      "visibility": "public",
      "team_id": "string",
      "project_id": "P00001",
      "created_at": "2026-09-25T12:00:00Z",
      "updated_at": "2026-09-25T12:00:00Z",
      "tasks_total": 25,
      "tasks_completed": 15,
      "progress_percent": 60,
      "leads": [
        {
          "user_id": "string",
          "username": "string",
          "assigned_by": "string",
          "assigned_at": "2026-09-25T12:00:00Z"
        }
      ],
      "position": 0
    }
  ],
  "next_cursor": "string"
}
```

### 304

Not Modified — `If-None-Match` matched the current `ETag` (no body)

### 400

Bad request — a query parameter outside what the operation accepts (`invalid-parameter`)

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Bad request",
  "status": 400,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 401

Missing or invalid bearer token

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Missing or invalid bearer token",
  "status": 401,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 403

Authenticated, but not allowed

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Authenticated, but not allowed",
  "status": 403,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 404

Not found

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Not found",
  "status": 404,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 409

Conflict (a duplicate, or an `Idempotency-Key` still in flight)

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Conflict (a duplicate, or an `Idempotency-Key` still in flight)",
  "status": 409,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 412

`If-Match` does not match the current `ETag`

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "`If-Match` does not match the current `ETag`",
  "status": 412,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 422

The body or query did not validate (`validation`), or an `Idempotency-Key` was reused

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "The body or query did not validate (`validation`), or an `Idempotency-Key` was reused",
  "status": 422,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 429

An access token over its per-minute limit (`rate-limit`; see `Retry-After`)

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "An access token over its per-minute limit (`rate-limit`; see `Retry-After`)",
  "status": 429,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

### 500

Unexpected server error — quote `request_id`

application/problem+json

_Problem_

An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support.

object

**type**

required

`about:blank` or a `urn:tasksmate:problem:*` identifier

string

Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused

**title**

required

string

**status**

required

integer

**detail**

required

Human-readable explanation (a string; for a 422, the list of validation errors)

**instance**

required

string

**request\_id**

required

string

**errors**

Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter

Array<object>

object

Example

```json
{
  "type": "about:blank",
  "title": "Unexpected server error",
  "status": 500,
  "detail": "…",
  "instance": "/v1/…",
  "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
}
```

---
Source: https://developers.tasksmate.indrasol.com/reference/operations/projectslist/