Update an existing blend. Returns the full updated blend resource.
API key authentication. Create API keys in the Supermetrics Hub and send
them in the Authorization header:
Authorization: Bearer <your-api-key>
ID of the team
ID of the blend to update
Blend fields to update
{
"display_name": "Example Blend Updated",
"description": "Updated example blend description",
"blended_data_sources": [
{
"data_source_id": "GA4",
"blend_data_source_id": 1,
"blend_data_source_key": null,
"display_name": "Google Analytics 4",
"report_type": null,
"report_type_settings": [],
"data_source_settings": [],
"accounts": [],
"segments": []
},
{
"data_source_id": "GADS",
"blend_data_source_id": null,
"blend_data_source_key": "efgh5678",
"display_name": "Google Ads",
"report_type": null,
"report_type_settings": [],
"data_source_settings": [],
"accounts": [],
"segments": []
}
],
"config": {
"query_table": {
"blend_data_source_id": 1
},
"joins": [
{
"join_table": {
"blend_data_source_key": "efgh5678"
},
"type": "left",
"conditions": [
{
"operator": "=",
"left": {
"blend_data_source_id": 1,
"datasource_field_name": "Date",
"datasource_field_display_name": "Date",
"datasource_field_type": "dim",
"datasource_field_data_type": "string.time.date",
"field_source": "standard",
"meta": null
},
"right": {
"blend_data_source_id": null,
"blend_data_source_key": "efgh5678",
"datasource_field_name": "Date",
"datasource_field_display_name": "Date",
"datasource_field_type": "dim",
"datasource_field_data_type": "string.time.date",
"field_source": "standard",
"meta": null
}
}
]
}
],
"fields": [
{
"blend_field_name": "impressions",
"blend_field_display_name": "Impressions",
"blend_datasource_fields": [
{
"blend_data_source_id": 1,
"datasource_field_name": "Impressions",
"datasource_field_display_name": "Impressions",
"datasource_field_type": "met",
"datasource_field_data_type": "int.number.value",
"field_source": "standard",
"meta": null
}
]
}
]
}
}Payload for updating an existing blend. Extends BlendBaseRequest. The blend type cannot be changed and is therefore omitted. Existing data sources are referenced by blend_data_source_id; newly added ones use blend_data_source_key.
Display name of the blend.
Optional free-text description of the blend.
Data sources to include in the blend.
Data source to include in the blend. At least one of blend_data_source_id or blend_data_source_key must be non-null: use blend_data_source_key when creating a new data source, blend_data_source_id for an existing one.
Data source identifier (e.g. the connector ID).
Internal ID of the blended data source. Use when updating an existing data source in the blend; null when creating a new one.
Temporary key linking a new data source to field/join references within the same request. Required when creating a blend. Must be exactly 8 lowercase alphanumeric characters.
Display name of the data source. Defaults to the data source name if omitted.
Settings to apply when querying this data source.
A single key/value setting applied to the data source query.
Setting ID.
Setting value — null, string, integer, or boolean.
Accounts to query from this data source.
An account selected for this data source.
Account identifier.
Account display name.
Group the account belongs to, if any.
Username used to authenticate with the data source.
Display name of the data source username.
Segments to apply when querying this data source.
A segment selected for this data source.
Segment identifier.
Segment display name.
Report type ID, if the data source supports report types.
Settings specific to the selected report type.
A single key/value setting for the selected report type.
Report type setting ID.
Setting value — null, string, integer, or boolean.
Field mappings and join configuration for the blend.
Primary (left-hand) data source — present for join blends only. Provide blend_data_source_key when creating, blend_data_source_id when updating with an existing data source.
Internal ID of the primary data source.
Key of the primary data source (for new data sources).
Join definitions — present for join blends only.
Join definition between the primary table and one other data source (request).
Data source to join with the primary table. Provide blend_data_source_key when creating, blend_data_source_id when updating with an existing data source.
Internal ID of the data source to join.
Key of the data source to join (for new data sources).
Join type.
Conditions that define how the two data sources are joined.
A condition comparing one field from each data source (request).
Comparison operator.
Field from the primary table.
Internal ID of the blended data source. Use for existing data sources when updating a blend; null when referencing a new data source by key.
Temporary key linking a new data source to field/join references within the same request. Required when creating a blend; used for new data sources when updating. Must be exactly 8 lowercase alphanumeric characters.
Field name as defined by the data source.
Display name of the field.
Field type: dim (dimension) or met (metric).
Data type of the field (e.g. string.time.date, int.number.value).
Origin of the field: standard = from the data source, transformation = computed field, data_source_account_custom = account-level custom field.
Optional metadata, e.g. account-level overrides.
Field from the join table.
Internal ID of the blended data source. Use for existing data sources when updating a blend; null when referencing a new data source by key.
Temporary key linking a new data source to field/join references within the same request. Required when creating a blend; used for new data sources when updating. Must be exactly 8 lowercase alphanumeric characters.
Field name as defined by the data source.
Display name of the field.
Field type: dim (dimension) or met (metric).
Data type of the field (e.g. string.time.date, int.number.value).
Origin of the field: standard = from the data source, transformation = computed field, data_source_account_custom = account-level custom field.
Optional metadata, e.g. account-level overrides.
Field definitions for the blend.
A blend field and its mapping to fields in each data source (request).
Unique name of the blend field — cannot be changed once created.
Display name of the blend field.
Per-data-source field mappings for this blend field.
A field reference within a data source (request). At least one of blend_data_source_id or blend_data_source_key must be non-null. When creating a blend (POST), use blend_data_source_key. When updating (PUT), use blend_data_source_id for existing data sources or blend_data_source_key for newly added ones.
Internal ID of the blended data source. Use for existing data sources when updating a blend; null when referencing a new data source by key.
Temporary key linking a new data source to field/join references within the same request. Required when creating a blend; used for new data sources when updating. Must be exactly 8 lowercase alphanumeric characters.
Field name as defined by the data source.
Display name of the field.
Field type: dim (dimension) or met (metric).
Data type of the field (e.g. string.time.date, int.number.value).
Origin of the field: standard = from the data source, transformation = computed field, data_source_account_custom = account-level custom field.
Optional metadata, e.g. account-level overrides.
Blend updated successfully
{
"meta": {
"request_id": "wmCedcnSca2ZZ8bJehrmeLBLq6SCSSeT"
},
"data": {
"blend_id": 569,
"blend_uuid": "71bc0582-31b5-11f1-a55c-4201ac182030",
"type": "union",
"display_name": "Example Blend Updated",
"description": "Updated example blend description",
"modified_time_utc": "2026-04-07T10:00:00Z",
"last_modify_user_email": "user@supermetrics.com",
"blended_data_sources": {
"items": [
{
"blend_data_source_id": 1,
"blend_id": 569,
"data_source_id": "GA4",
"display_name": "Google Analytics 4",
"accounts": {
"items": []
},
"segments": {
"items": []
},
"data_source_settings": {
"items": []
},
"report_type_settings": {
"items": []
}
}
]
},
"config": {
"fields": {
"items": [
{
"blend_field_name": "impressions",
"blend_field_display_name": "Impressions",
"blend_field_type": "met",
"blend_field_data_type": "int.number.value",
"blend_datasource_fields": {
"items": [
{
"blend_data_source_id": 1,
"datasource_field_name": "Impressions",
"datasource_field_display_name": "Impressions",
"datasource_field_type": "met",
"datasource_field_data_type": "int.number.value",
"field_source": "standard",
"meta": null
}
]
}
}
]
}
}
}
}Success envelope wrapping a single blend.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
A blend with its fields and data sources, as returned for a single-blend read.
Blend ID.
Blend UUID.
Blend type.
Display name of the blend.
Description of the blend.
Timestamp of the last modification, in UTC. Serialized with a numeric offset (e.g. "+0000") rather than a trailing "Z".
Email of the user who last modified the blend.
Data sources included in this blend.
Data source items.
A data source included in the blend response, with field mappings and account details.
Internal ID of the blended data source.
ID of the blend this data source belongs to.
Data source identifier.
Display name of the data source.
Settings applied when querying this data source.
Setting items.
A single data source setting.
Accounts queried from this data source.
Account items.
An account queried from this data source.
Segments applied when querying this data source.
Segment items.
A segment applied when querying this data source.
Report type ID.
Settings for the selected report type.
Report type setting items.
A single setting for the selected report type.
Data source logo URL.
Field mappings and join configuration for the blend (response). Union blends contain only fields; join blends also include query_table and joins.
Primary (left-hand) data source — present for join blends only.
Internal ID of the primary data source.
Join definitions — present for join blends only.
Join items.
Join definition between two data sources (response).
Data source joined with the primary table.
Internal ID of the data source to join.
Join type.
Conditions that define how the two data sources are joined.
Condition items.
A condition comparing one field from each data source (response).
Comparison operator.
Field from the primary table.
Internal ID of the blended data source.
Field name as defined by the data source.
Display name of the field.
Field type: dim (dimension) or met (metric).
Data type of the field (e.g. string.time.date, int.number.value).
Origin of the field: standard = from the data source, transformation = computed field, data_source_account_custom = account-level custom field.
Optional metadata, e.g. account-level overrides.
Field from the join table.
Internal ID of the blended data source.
Field name as defined by the data source.
Display name of the field.
Field type: dim (dimension) or met (metric).
Data type of the field (e.g. string.time.date, int.number.value).
Origin of the field: standard = from the data source, transformation = computed field, data_source_account_custom = account-level custom field.
Optional metadata, e.g. account-level overrides.
Field definitions for the blend.
Field items.
A blend field and its mapping to fields in each data source (response).
Unique name of the blend field — cannot be changed once created.
Display name of the blend field.
Field type: dim (dimension) or met (metric).
Data type of the field (e.g. string.time.date, int.number.value).
Per-data-source field mappings for this blend field.
Datasource field items.
A field reference within a data source (response).
Internal ID of the blended data source.
Field name as defined by the data source.
Display name of the field.
Field type: dim (dimension) or met (metric).
Data type of the field (e.g. string.time.date, int.number.value).
Origin of the field: standard = from the data source, transformation = computed field, data_source_account_custom = account-level custom field.
Optional metadata, e.g. account-level overrides.
Bad request - invalid parameters
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "BAD_REQUEST",
"message": "The request was invalid."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.
Unauthorized
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.
Permission denied
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "PERMISSION_ERROR",
"message": "You do not have permission to perform this action."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.
Resource not found
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "NOT_FOUND",
"message": "The requested resource was not found."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.
Too Many Requests
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "TOO_MANY_REQUESTS",
"message": "Rate limit exceeded. Retry later."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.
Internal server error
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "An unexpected error occurred."
}
}Standard envelope returned by all error (4xx/5xx) responses.
Metadata included in every API response.
Unique identifier for the request, for tracking and debugging.
Machine- and human-readable detail for a failed request.
Stable, screaming-snake-case identifier for the error condition. Clients should branch on this, not on message. Common values include BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT_ERROR, PERMISSION_ERROR, UNPROCESSABLE_ENTITY, UNPROCESSABLE_CONTENT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR, DUPLICATION_FAILED, SERVICE_UNAVAILABLE; domains may define additional codes.
Short, human-readable summary of the error.
Optional longer explanation specific to this occurrence.