---
title: "Update a metrics view"
method: PATCH
path: "/api/v1/metrics-views/{id}"
tags: ["Views"]
---

# Update a metrics view

`PATCH /api/v1/metrics-views/{id}`

## Request

- Base URL: `https://api.recruitwithatlas.com`
- URL: `https://api.recruitwithatlas.com/api/v1/metrics-views/{id}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/recruitwithatlas/apis/atlas-api/docs/api/v1/metrics-views/:id/patch.ts> (a function with typed inputs; its response is checked against the schema)

Changes a saved dashboard. Send at least one field; each one replaces its value wholesale, so `metricsCard`, `metricsColumn`, `sorting` and the filter arrays are not merged into what is already stored. `visibility`, `isCollaborative`, `teamId`, `position` and `ownerId` are owner-only, and `ownerId` must be an active user in the agency. Other users may change the rest when the view is collaborative (anyone who can see it) or when they are a member of the view's team (`teamId`), collaborative or not. System views cannot be changed at all.

## Path parameters

- `id` string, uuid, required: Metrics view ID

## Request body

- object
  - `name` string: New view name
  - `position` integer: Order within the owner's list, from `0` — owner only. A position past the end moves the view last
  - `ownerId` string, uuid: Transfers the view to another user. Must be an active user in the agency — owner only
  - `description` string: Free-text description
  - `visibility` 'public' | 'team' | 'private': Who can see the view — owner only
  - `isCollaborative` boolean: Whether anyone who can see the view may change it. Members of the view's team can change it either way
  - `sorting` object[]: Saved sort order
    - `id` string, required: Metric or column ID to sort on
    - `direction` 'ASC' | 'DESC' | 'asc' | 'desc', required: Sort direction. Lowercase is accepted and stored uppercase
  - `timeFrame` 'Today' | 'Yesterday' | 'This week' | 'Last week' | 'This month' | 'Last month' | 'This quarter' | 'Last quarter' | 'This year' | 'Last year' | 'Last 30 days' | 'Last 90 days' | 'Last 180 days' | 'All time' | 'null', nullable: Named relative period the dashboard defaults to
  - `from` string, date-time, nullable: Start of a fixed date range. Ignored when `timeFrame` is set
  - `to` string, date-time, nullable: End of a fixed date range. Ignored when `timeFrame` is set
  - `teamsToFilter` string[]: Team IDs the dashboard is scoped to
  - `usersToFilter` string[]: User IDs the dashboard is scoped to
  - `metricsCard` string[]: Metrics registry row IDs shown as cards. Unknown IDs are rejected with 400
  - `metricsColumn` object[]: Metrics shown as table columns, left to right
    - `id` string, uuid, required: Metrics registry row ID
    - `visible` boolean, required: Whether the column is shown
  - `teamId` string, uuid, nullable: Team the view belongs to. IDs outside the agency are rejected with 400
  - `refreshRate` integer: Auto-refresh interval in seconds. `0` disables it

## Response `200`

Metrics view updated

- object
  - `status` 'ok', required
  - `data` object, required
    - `id` string, uuid, required: Metrics view ID
    - `name` string, required: View name
    - `description` string, required: Free-text description
    - `visibility` 'public' | 'team' | 'private', required: Who can see the view
    - `isCollaborative` boolean, required: Whether viewers of a shared view may change it
    - `isSystem` boolean, required: Whether Atlas ships the view — system views are read-only through the API
    - `position` integer, required: Order within the owner's own view list
    - `refreshRate` integer, required: Auto-refresh interval in seconds; `0` disables it
    - `sorting` object[], required: Saved sort order
      - `id` string, required
      - `direction` string, required: `ASC` or `DESC`
    - `timeFrame` string, nullable, required: Named relative period the dashboard defaults to
    - `from` string, date-time, nullable, required: Start of a fixed date range
    - `to` string, date-time, nullable, required: End of a fixed date range
    - `teamsToFilter` string[], required: Team IDs the dashboard is scoped to
    - `usersToFilter` string[], required: User IDs the dashboard is scoped to
    - `metricsCard` string[], required: Metrics registry row IDs shown as cards
    - `metricsColumn` object[], required: Metrics shown as table columns, left to right
      - `id` string, uuid, required
      - `visible` boolean, required
    - `teamId` string, uuid, nullable, required: Team the view belongs to
    - `owner` object, required: The user who owns the view
      - `id` string, uuid, required
      - `name` string, required: "Deleted user" when the owner has been deleted
      - `deleted` boolean, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: The request named a metric that does not exist in this agency
- `401`: Unauthorized - missing or invalid API key
- `403`: The view is visible to you, but you may not change it — system views are read-only, and only the owner may change a shared view
- `404`: The view does not exist, belongs to another agency, or is not visible to you
- `415`: The request carried a body without `Content-Type: application/json`
- `422`: Validation error - the request failed schema validation (`errors.fieldErrors`) or a business rule (`errors.formErrors`)
- `429`: Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the "Rate limits" section of the introduction for details.
- `500`: Internal server error
- `501`: Endpoint is disabled in this environment. Not a routing error — do not retry.

## Changes

- **2026-11-03** `158ee454751c`: 1 info
  - added the new `undefined` enum value to the request property `timeFrame`
- **2026-10-16** `2c0c6a89d8e7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/recruitwithatlas/apis/atlas-api/changes/api/v1/metrics-views/:id/patch.md)

---

[API](https://skmtc.dev/recruitwithatlas/apis/atlas-api.md) - [All operations](https://skmtc.dev/recruitwithatlas/apis/atlas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/recruitwithatlas/apis/atlas-api/revisions/158ee454751c?raw)