Field Reference

Every field the public API exposes, per asset, on one page — and for each one, whether you can write it. The API Reference tab carries the same shape per endpoint; this page exists so you (or an agent) can see all of it in a single fetch, and because "read-only" here has three distinct meanings that a plain OpenAPI readOnly flag cannot express — see the table below.

The tables are generated from the same schemas that validate live requests, so they cannot drift from what the API actually accepts.

Access

Access	On create (`POST`)	On update (`PUT`)
Editable	Sent as you like; `required` ones must be present	Sent as you like; a `required` field must be present on every write, and an omitted editable field is cleared, since `PUT` replaces rather than merges
Editable, sometimes required	Required only in some cases, in one of two ways. Either whether it is required depends on the other fields you send — a metric's `sourceId` is required unless the metric is calculated — or it is a field of an array's items, mandatory on every element you send while the array itself may be omitted: a metric's `dimensions.name`, a goal's `triggers.type`. Read the field's note either way	Same
Read-only	Ignored — send it or don't, nothing is applied	Ignored while it matches the stored value, so a spec fetched with `GET` can be sent straight back. Sending a different value is rejected with `400`, naming the field and both values
Read-only, never compared	Ignored	Ignored, always — these change on their own (a metric that refreshes moves `status` and `dataUpdatedAt`), so a value that went stale between your `GET` and your `PUT` is never an error
Read-only (no write endpoint)	n/a — the whole asset is read-only today: no endpoint accepts it as a request body, so nothing about it can be written	n/a

So the round trip works without pre-processing: GET an asset, change the editable fields you care about, PUT the whole thing back. You only see a read-only 400 if you actually tried to change one — most often by reusing a body across two different assets, so that its id no longer matches the one in the URL.

Two rules that are easy to miss, both covered in Getting Started:

A PUT replaces. An editable field you leave out is cleared, not preserved — including nested objects, which are replaced whole rather than merged key by key.
An update reads the asset before it validates the body, so a write to something that does not exist answers 404 even when the body is invalid too.

A version field accompanies every asset in responses. It is not listed below: it names the mapper version rather than describing the asset, and if you send it on a write it must equal "1.0".

Metric

A public metric asset. Every metric names its source in sourceId, except a calculated one: that omits sourceId, fieldId, timeZone and refreshStatus entirely (its dimensions also omit fieldId and dataType) and is written by sending a formula instead. Written by POST /metrics and PUT /metrics/:metricId. See Metrics.

Field	Type	Access	Notes
`id`	string	Read-only	The unique identifier of the metric.
`ownerUserId`	string	Read-only	—
`sourceId`	string	Editable, sometimes required	The id of the source the metric reads from - a data feed, direct connection or cube, depending on sourceType. Required on every write except a calculated metric, which has no source.
`timeRefId`	string	Editable	—
`fieldId`	string	Editable	—
`createdAt`	string (date-time)	Read-only, never compared	—
`updatedAt`	string (date-time)	Read-only, never compared	—
`dataUpdatedAt`	string (date-time)	Read-only, never compared	—
`status`	string	Read-only, never compared	One of: `OK`, `LOADING_DATA`, `FAILED`, `EMPTY`, `BACKFILL_DATA`, `MISSING_FEATURES`.
`name`	string	Editable, required	—
`description`	string	Editable	—
`timeRangeStart`	string (date-time)	Read-only, never compared	—
`timeRangeEnd`	string (date-time)	Read-only, never compared	—
`timeZone`	string	Editable	—
`positiveDirection`	string	Editable	One of: `UP`, `DOWN`, `NEUTRAL`.
`missingValues`	string	Editable	—
`sourceType`	string	Editable	One of: `DATAFEED`, `CALCULATED`, `DBT`, `SQL`, `CUBE`. The metric's source type. Internally this metric-creation path is named 'formula' (unrelated to the public `formula` field below, which is specific to calculated metrics) and is surfaced here as 'DATAFEED'; calculated metrics always report 'CALCULATED'.
`locked`	boolean	Editable	—
`numeric`	boolean	Editable	—
`formula`	string	Editable	—
`refreshStatus`	string	Editable	Not a fixed set of values: 'OK' on success, otherwise an upper-cased free-text failure message (e.g. 'FAILED - PROFILE NOT FOUND: ...').
`properties.aggregation`	string	Editable	How the metric's values are rolled up, e.g. 'SUM', 'MEAN', 'COUNT' or 'DISTINCT_COUNT'. A DATAFEED- or SQL-sourced create that omits it is stored with 'SUM', or 'COUNT' when the metric is not numeric; the other source types derive their aggregation from the formula or the upstream definition.
`properties.numberFormat`	string	Editable	How the metric's value is rendered: 'NUMERIC' for a plain number, 'CURRENCY' alongside currencyCode, 'PERCENTAGE', or 'DURATION'. A create that omits it (or omits properties entirely) is stored with 'NUMERIC'.
`properties.currencyCode`	string	Editable	—
`properties.cumulative`	boolean	Editable	—
`properties.timelessData`	boolean	Editable	—
`properties.lockAggregation`	boolean	Editable	—
`properties.iconId`	string	Editable	—
`properties.iconType`	string	Editable	—
`properties.dataShape`	string	Editable	One of: `TRANSACTIONAL`, `SNAPSHOT`. Whether the metric accumulates over time ('TRANSACTIONAL') or shows the most recent single point ('SNAPSHOT'). See snapshotPeriod for how often a SNAPSHOT metric resets.
`properties.snapshotPeriod`	string	Editable	—
`properties.tableName`	string	Editable	SQL-sourced metrics only (`sourceType: 'SQL'`). The table the metric's field belongs to, from GET /direct_connections/:connectionId/tables.
`properties.slMetricType`	string	Read-only	dbt-sourced metrics only. The semantic layer metric type, e.g. `SIMPLE` or `RATIO`.
`properties.supportedPeriodicities`	string	Read-only	dbt-sourced metrics only. Comma-separated list of the periodicities the metric can be queried at, e.g. `1d,1w,1mo`.
`properties.slForceGroupOnTime`	string	Read-only	dbt-sourced metrics only. The dbt grain a cumulative grain-to-date metric must be grouped by, which fixes the periodicity it is queried at — one of `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`.
`properties.slForceGroupOnTimeAggregation`	string	Read-only	dbt-sourced metrics only. Which value in each `slForceGroupOnTime` period represents it — `FIRST` or `LAST`.
`dimensions.id`	string, per item	Editable	—
`dimensions.name`	string, per item	Editable, sometimes required	—
`dimensions.fieldId`	string, per item	Editable	—
`dimensions.dataType`	string, per item	Editable	One of: `STRING`, `DATE`, `DOUBLE`, `BOOLEAN`. The dimension's type. A DATAFEED-sourced metric's dimensions are always 'STRING', so a create may omit it; for a SQL- or CUBE-sourced metric send the connection's own column type translated onto this enum.

Dashboard

A public dashboard asset. No create/update endpoint accepts this asset today, so every field is read-only. See Dashboards.

Field	Type	Access	Notes
`id`	string	Read-only (no write endpoint)	The unique identifier of the dashboard.
`name`	string	Read-only (no write endpoint)	—
`ownerUserId`	string	Read-only (no write endpoint)	—
`createdAt`	string (date-time)	Read-only (no write endpoint)	—
`updatedAt`	string (date-time)	Read-only (no write endpoint)	—

Goal

A public goal asset. Written by POST /goals and PUT /goals/:goalId. See Goals.

Field	Type	Access	Notes
`id`	string	Read-only	The unique identifier of the goal.
`ownerId`	string	Read-only	—
`name`	string	Editable, required	—
`type`	string	Editable, required	One of: `THRESHOLD`, `RECURRING_TARGET`, `CUSTOM_TARGET`, `RANGE`. The goal's type, determining payload shape and evaluation behavior.
`payload`	object	Editable	Goal-type-specific configuration. THRESHOLD: value, thresholdType ('ABOVE'\|'BELOW'), valueType ('VALUE'\|'METRIC'), notifyOptions. RANGE: lowerValue, upperValue, notifyOptions (e.g. ['CROSSED_INSIDE'] or ['CROSSED_OUTSIDE']). RECURRING_TARGET: value, recurringPeriod (e.g. 'D'\|'w'\|'M'), notifyOptions (e.g. ['PERIOD_END', 'VALUE_REACHED']). CUSTOM_TARGET: customGranularity, values (an array of {coordinate, value}). notifyOptions is an array of strings for every goal type that takes it, even when it holds a single option.
`scopes`	object	Editable	The metrics this goal applies to: {metrics: [<metric id>, ...]}. No other scope types exist today. A metric scope is practically required on create: without one, goal creation fails (403) on the share-rights check. When present, its id is attached to each trigger internally.
`triggers.type`	string, per item	Editable, sometimes required	One of: `event.updated.metric.data`, `event.updated.schedule.period_end`. 'event.updated.metric.data' fires on new metric data (metric-scoped goals); 'event.updated.schedule.period_end' fires on a recurring schedule.
`createdAt`	string (date-time)	Read-only, never compared	—
`updatedAt`	string (date-time)	Read-only, never compared	—

Tag

A public tag asset. Written by POST /tags and PUT /tags/:tagId. See Tags.

Field	Type	Access	Notes
`id`	string	Read-only	The unique identifier of the tag.
`ownerId`	string	Read-only	—
`name`	string	Editable, required	—
`description`	string	Editable	—
`config`	object	Editable	The tag's display configuration: {colour}. colour accepts a hex/rgb/hsl color, a CSS4 color name, or a var(--token) reference; a random theme color is assigned if omitted.
`createdAt`	string (date-time)	Read-only, never compared	—
`updatedAt`	string (date-time)	Read-only, never compared	—

DataFeed

A public data feed asset. Written by PUT /data_feeds/:feedId. See Data Feeds.

Field	Type	Access	Notes
`id`	string	Read-only	The unique identifier of the data feed.
`ownerUserId`	string	Editable	—
`createdAt`	string (date-time)	Read-only, never compared	—
`last_refresh_outcome`	string	Read-only, never compared	One of: `success`, `error`.
`last_successful_refresh_timestamp`	string (date-time)	Read-only, never compared	—
`is_locked`	boolean	Editable	—
`name`	string	Editable	—
`description`	string	Editable	—
`joined_to_ids`	array of string	Read-only	—
`columns.id`	string, per item	Editable	—
`columns.useCustomName`	boolean, per item	Editable	—
`columns.autoDetect`	boolean, per item	Editable	—
`columns.formula`	string, per item	Editable	A datasource-qualified reference to the column's source field is surfaced as the placeholder 'source@' and translated back to the real datasource id on write.
`columns.name`	string, per item	Editable	—
`columns.type`	string, per item	Editable	One of: `TEXT`, `NUMERIC`, `DATE`.
`columns.fmtArgs`	object, per item	Editable	Column-specific format arguments; shape varies by the column's format.
`columns.aggregation`	string, per item	Editable	—
`source.connector`	string	Editable	—
`source.format`	string	Editable	—
`source.refresh_interval`	number	Editable	Refresh interval in seconds, e.g. 3600 for hourly. 0 means the feed is never automatically refreshed.
`source.is_dynamic`	boolean	Editable	—
`source.disabled`	boolean	Editable	—
`source.date_last_refresh`	string (date-time)	Read-only, never compared	—
`source.query`	object	Editable	The query-builder query the data source pulls, for a feed generated from a service connection - the same shape POST /data_feeds/generate?type=queryBuilder takes, each field named by `name`. Absent for a data source that has no query of its own (an upload, or a REST endpoint), which also cannot be given one. Writable: sending it replaces the query wholesale (send the full field list, read from a GET immediately before) and the data source is refreshed. A query-builder column addresses its source field by POSITION, so send the matching `columns` in the same request - the field order in `fields` is the column order, A, B, C..., hidden fields excluded. A field marked `hidden` is a parameter the service requires to answer the query rather than a column of the feed; leave it out and it is carried over.

DirectConnection

A public direct connection asset (metrics-service-backed). Written by POST /direct_connections and PUT /direct_connections/:connectionId. See Direct Connections.

Field	Type	Access	Notes
`id`	string	Read-only	The unique identifier of the connection.
`name`	string	Editable	—
`dataBaseType`	string	Editable, required	Always required; identifies the connector type, e.g. 'postgresql', 'snowflake', 'redshift', 'bigquery', 'databricks', 'mariadb', 'aurora', 'azuresql', 'azuresynapse', 'dbt', 'cube', 'sample'. A dbt semantic-layer connection reports 'dbt', which is also how you create one. Each connector defines its own connectionFields parameter names.
`ownerId`	string	Editable	The user who owns the connection. Listed connections are the ones you own plus the ones shared across the account.
`isShared`	boolean	Editable, required	Whether the connection is shared with every user in the account.
`connectionFields`	object	Editable	Connector-specific configuration; field names vary per dataBaseType (e.g. postgresql uses user/_host/_port/_database/currentSchema). Populated only for a connection you own (and for the built-in sample connection) - an empty object for one shared across the account. Within your own connection, secret fields (password, private keys) are omitted rather than masked - but an update preserves any secret whose key it does not send, so a spec read from here can be sent straight back to PUT. Send a secret only to change it; sending it empty clears it.

DataFeedConnection

A public data feed connection asset (web-UI-service-backed, read-only). No create/update endpoint accepts this asset today, so every field is read-only. See Data Feed Connections.

Field	Type	Access	Notes
`id`	string	Read-only (no write endpoint)	The unique identifier of the connection.
`name`	string	Read-only (no write endpoint)	—
`serviceProvider.name`	string	Read-only (no write endpoint)	—
`serviceProvider.serviceKey`	string	Read-only (no write endpoint)	—
`state.key`	string	Read-only (no write endpoint)	One of: `ACTIVE`, `REVOKED`, `DISABLED`.

ServiceProvider

A service provider that connections can be created against - Salesforce, GA4, and so on (web-UI-service-backed, read-only). Discovery only: the listing carries the identifiers other endpoints take, not the provider's auth configuration or branding. No create/update endpoint accepts this asset today, so every field is read-only. See Service Providers.

Field	Type	Access	Notes
`id`	string	Read-only (no write endpoint)	The unique identifier of the service provider.
`name`	string	Read-only (no write endpoint)	Display name, e.g. 'Google Analytics 4'.
`description`	string	Read-only (no write endpoint)	What the provider connects to. Absent when the provider has no description.
`serviceKey`	string	Read-only (no write endpoint)	Stable key identifying the provider, e.g. 'c3po_gaV4'. This is the same value a data feed connection reports as `serviceProvider.serviceKey`.