--- title: "List projects" canonical: "https://admiral.io/docs/api/projects/ProjectAPI_ListProjects" --- # List projects `GET https://api.admiral.io/v1/projects` Scope: `project:read` ### Query parameters - `filter` (string): Filter expression to narrow results. Uses the Admiral filter DSL (see the API documentation for the full operator and predicate reference). Filterable fields: - `name`: filter by project name. - `labels.key`: filter by label key. Example: `field['name'] = 'inventory-api' AND field['labels.team'] = 'logistics'` Length at most 1024. - `page_size` (integer (int32)): Maximum number of projects to return per page. Defaults to 50 when omitted or 0; must not exceed 100. Value 0 to 100. - `page_token` (string): Opaque pagination token from a previous response. ### Response 200 Success - `projects` (array of Project): The list of projects. - `id` (string): Unique identifier for the project. Pattern `^prj-[0-9a-z]+$`. Read-only. - `name` (string): URL-safe, human-readable identifier (e.g., "inventory-api"). Unique within the organization. Lowercase alphanumeric and hyphens only, must start with a letter and end with an alphanumeric character (1-63 chars). Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. - `description` (string): Optional longer-form description of the project's purpose (e.g., "Core inventory service tracking warehouse stock and fulfillment"). Length at most 1024. - `labels` (map of string to string): Arbitrary key-value labels for organizing and filtering projects (e.g., `{"team": "logistics", "tier": "critical"}`). - `created_by` (ActorRef): The user or agent who created this project (server-populated from token). Read-only. - `id` (string): The actor's typed id: a `usr-` user id or an `sa-` service account id. - `display_name` (string): Human-readable name (e.g., "John Smith", "deploy-bot"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): When the project was created. Read-only. - `updated_at` (Timestamp): When the project was last updated. Read-only. - `next_page_token` (string): Pagination token for the next page. Empty when there are no more results.