---
title: "Fetching a list of Custom Field Values"
method: GET
path: "/custom_field_values"
tags: ["Custom Field Values"]
---

# Fetching a list of Custom Field Values

`GET /custom_field_values`

## Request

- Base URL: `https://api.mavenlink.com/api/v1`
- URL: `https://api.mavenlink.com/api/v1/custom_field_values`
- Auth: none declared

Returns all values for the specified set of
[Custom Fields](https://knowledge.kantata.com/hc/en-us/articles/202924760-Custom-Fields-Overview-#arrange).

This endpoint has its own rate limit. See the [Knowledge Base](https://knowledge.kantata.com/hc/en-us/articles/9698066628123) for more information.

Custom fields are organized into [sets](/tag/Custom-Field-Sets),
by the objects they store additional information for (Estimate, Project, Group, Resource, Task, or User).
Use the `subject_type` parameter to specify which set of Custom Fields to return values for:
* `Estimate`
* `Story` (Task)
* `User`
* `Workspace` (Project)
* `WorkspaceGroup` (Group)
* `Resource`

Custom field values for _archived_ Projects and Tasks are included in returned values.
Values are sorted from less to more recently updated.

##### Note:
The `read_access` [permission setting on each custom field](https://knowledge.kantata.com/hc/en-us/articles/202924760#see)
determines the minimum permission needed to view a custom field and its value.
* `Workspace` (Project), `Resource`, and `Story` (Task) custom fields are project-specific objects,
so their minimum permissions are set at the [project level](https://knowledge.kantata.com/hc/en-us/articles/115002779293-Project-Permissions):
  - `project_collaboration` (default)
  - `time_logging`
  - `financial`
  - `project_admin`

Most account-level permissions supercede project-level permissions. Therefore, Account Administrators
are able to view all Project, Resource, and Task custom fields and values across the account,
regardless of project participation or `read_access` settings.
* `Estimate`, `WorkspaceGroup` (Group), and `User` custom fields are account-wide objects, so their minimum permissions are
set at the [account level](https://knowledge.kantata.com/hc/en-us/articles/203041364):
  - `account_collaboration`
  - `project_creator`
  - `project_lead`
  - `reports_viewer`
  - `reports_viewer_with_cost`
  - `account_admin` (default)


This endpoint returns structured Custom Field Value objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `custom_field_values` top-level JSON key.
Please see our [Response Format](#section/Response-Format) section for more information.

## Query parameters

- `subject_type` string, required
- `created_after` string, date-time
- `created_before` string, date-time
- `external_reference_external_message` string
- `external_reference_external_status` string
- `external_reference_service_model` string
- `external_reference_service_model_ref` integer
- `external_reference_service_model_refs` string
- `external_reference_service_name` string
- `external_reference_status` string
- `has_external_references` boolean
- `include` string
- `only` string
- `order` string
- `page` integer
- `per_page` integer
- `updated_after` string, date-time
- `updated_before` string, date-time
- `with_custom_field_id` string
- `with_setter_id` string
- `with_subject_id` string
- `without_external_reference_service_name` string

## Response `200`

A list of Custom Field Values have been retrieved.

- object
  - `count` integer
  - `meta` object
    - `count` integer
    - `page_count` integer
    - `page_number` integer
    - `page_size` integer
  - `results` object[]
    - `key` string
    - `id` string
  - `custom_field_values` object
  - `external_references` object
  - `custom_fields` object
  - `users` object
  - `custom_field_choices` object
  - `stories` object
  - `workspaces` object
  - `workspace_groups` object

## Other responses

- `400`: Bad Request
- `401`: Unauthorized request
- `403`: Forbidden request
- `404`: Page Not Found
- `422`: Unprocessable Entity
- `503`: Service is unavailable

---

[API](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation.md) - [All operations](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation/revisions/9d4ebed2fa98?raw)