---
title: "List projects by metadata"
method: GET
path: "/projects/list_by_metadata_key"
tags: ["Projects"]
---

# List projects by metadata

`GET /projects/list_by_metadata_key`

Returns projects that match the provided metadata key-value pair. The metadata key and value must match exactly. Returns a 404 if no project is found.

## Query parameters

- `metadata_key` string, required
- `metadata_value` string, required

## Response `200`

successful

- object
  - `data` ProjectExtended[]
    - `id` integer
    - `name` string
    - `tax_year` integer, nullable — Four-digit year parsed from the project name, or null if the name contains no recent year.
    - `idempotency_key` string
    - `metadata` object
    - `due_date` string, date-time
    - `reminder_schedule_name` string, nullable — Name of the project's reminder schedule, or null if none is set.
    - `assignees` AssigneeWithContact[]
      - `id` integer
      - `display_name` string
      - `name` string
      - `email` string, nullable — Contact's global primary email, or null if the contact has none.
      - `magic_link` string — Assignee's magic upload URL.
      - `contact` EntityContactSummary — Summary representation of a contact. Scalar attributes only — no emails, phones, addresses, tags, or linked entities. Use GET /contacts/{contact_id} for the ContactExtended representation that includes those.
        - `id` integer
        - `first_name` string
        - `last_name` string
        - `nick_name` string
        - `company` string
        - `job_title` string
        - `client_id_number` string
        - `created_at` string, date-time
        - `updated_at` string, date-time
        - `effective_email` EffectiveEmail, nullable — The email to use for this contact in the containing entity or project context. Falls back to the contact's global primary email.
          - `id` integer
          - `email` string, email
          - `overridden` boolean — Whether an entity-level override selected this email.
          - `source` 'manual' | 'cch_axcess' | 'null', nullable — Source of the entity-level override, or null when using the global primary email.
    - `tasks` Task[]
      - `id` integer
      - `name` string — Name of the task
      - `description` string — Description of the task - supports limited subset of HTML <b>, <ul>, <li>, <br>, and <a>.
      - `status` 'to_do' | 'pending_review' | 'approved' — Status of the task
    - `user` User
      - `id` integer
      - `email` string
      - `first_name` string
      - `last_name` string
      - `idempotency_key` string, nullable
    - `tags` Tag[]
      - `id` integer
      - `name` string
    - `entity` Entity — Summary representation of an entity. Contains scalar attributes only — no contacts, projects, or tags. Use GET /entities/{id}, or GET /entities?extended_view=true, for the EntityExtended representation that includes those associations.
      - `id` integer
      - `client_id_number` string
      - `name` string
      - `entity_type` string
      - `metadata` object — Additional metadata for the entity, contents may vary
      - `ein` string — Employer Identification Number (EIN)
      - `other_ids` object — Other identifying information, contents may vary
      - `created_at` string, date-time
      - `updated_at` string, date-time
    - `project_status` ProjectStatus
      - `id` integer
      - `name` string
      - `position` integer

## Other responses

- `404` — project not found

---

[API](https://skmtc.net/gettruss/apis/api-v1.md) · [All operations](https://skmtc.net/gettruss/apis/api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gettruss/api-v1/versions/7c956b3d1bdf/schema)