---
title: "Update the properties of a call"
method: PATCH
path: "/v1/call/{callId}/properties"
tags: ["Call"]
---

# Update the properties of a call

`PATCH /v1/call/{callId}/properties`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/call/{callId}/properties`
- Auth: HTTP bearer

Add, overwrite or remove custom properties on an already-existing call. Use this for data that becomes available after the call was created, e.g. an outcome your system validates a few minutes later. Merge semantics: a value adds or overwrites the property, null removes it, and properties left out are untouched. The patch is applied whole or not at all: a property Roark sets itself, or a value whose type differs from the type the project already stores that property as, rejects the request with a 400 and nothing is written. A 409 means another request created one of the properties with a different value type at the same moment; nothing was written. Optionally pass `metrics` to (re)score metrics over the updated properties, which triggers a billed metric collection job and requires the `metric:create` permission.

## Path parameters

- `callId` string, uuid, required

## Request body

- UpdateCallPropertiesRequest: Add, overwrite or remove custom properties on an existing call, optionally (re)scoring metrics.
  - `properties` object, required: Properties to change on the call. A string, number or boolean value adds the property or overwrites it; null removes it. Properties left out are untouched. Keys are stored in snake_case, as on POST /v1/call. A property keeps the value type it was first stored with in the project, so a value of another type is rejected. Properties Roark sets itself (direction, duration_seconds, agent_id, ...) can't be changed. Max 100 per request.
  - `metrics` object[]: Optional. Metric definitions to (re)score on this call once the properties are written, e.g. metrics that read the call's properties. Triggers a metric collection job (billed, credit-gated) and requires the 'metric:create' permission. Omit to update properties without scoring. Max 20.
    - `id` string, uuid, required

## Response `200`

Properties updated on the call

- object
  - `data` UpdateCallPropertiesResponse, required: Result of updating the properties of a call.
    - `callId` string, uuid, required: The call whose properties were updated
    - `updated` string[], required: Stored (snake_case) names of the properties written by this request, including ones sent with the value they already had
    - `removed` string[], required: Stored names of the properties removed by this request. A property sent as null that was not on the call is not listed.
    - `properties` object, required: All of the call's properties after the update, including the ones Roark sets, when the key also has the 'call:read' permission. A key without it gets back only the properties this request wrote. Values are returned as strings, as on GET /v1/call/:callId.
    - `metricCollectionJob` MetricCollectionJobResponse, required: A metric collection job that processes metrics for calls or chats
      - `id` string, uuid, required: Unique identifier of the metric collection job
      - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELED', required: Current status of the job
      - `triggeredBy` 'USER_MANUAL' | 'USER_API' | 'METRIC_POLICY' | 'SIMULATION', required: What triggered this job
      - `totalItems` integer, required: Total number of call-metric pairs to process
      - `completedItems` integer, required: Number of items that finished without failing: a value was written, or the metric did not apply to the conversation
      - `failedItems` integer, required: Number of items that could not be computed, for example because an artifact the metric reads (such as diarization) failed to generate
      - `startedAt` string, nullable, required: When the job started processing
      - `completedAt` string, nullable, required: When the job completed
      - `errorMessage` string, nullable, required: Why the job failed or, on a COMPLETED job with failedItems above 0, why those items failed
      - `policyIds` string[], required: IDs of the metric policies that triggered this job
      - `createdAt` string, required: When the job was created
      - `updatedAt` string, required: When the job was last updated
    - `metricCollectionError` string, nullable, required: Present (non-null) only when `metrics` were requested but the collection job could not be started (e.g. insufficient credits, or an unknown metric id). The properties were still written. Retry scoring via POST /v1/metric/collection-jobs, or re-send this request (writing the same values again is harmless). Null on success or when no metrics were requested.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-10-16** `35c95f8bd347`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/call/:callId/properties/patch.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)