Create a new blend for a team. Returns the full blend resource.
Bearer token authentication. Include the token in the Authorization header:
Authorization: Bearer <your-token>
ID of the team
Blend to create
{
"type": "union",
"display_name": "Example Blend",
"description": "Example blend description",
"blended_data_sources": [
{
"data_source_id": "GA4",
"blend_data_source_id": null,
"blend_data_source_key": "abcd1234",
"display_name": "Google Analytics 4",
"report_type": null,
"report_type_settings": [],
"data_source_settings": [],
"accounts": [],
"segments": []
}
],
"config": {
"fields": [
{
"blend_field_name": "impressions",
"blend_field_display_name": "Impressions",
"blend_datasource_fields": [
{
"blend_data_source_id": null,
"blend_data_source_key": "abcd1234",
"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 creating a new blend. Extends BlendBaseRequest and additionally requires the blend type. When creating, new data sources are referenced by blend_data_source_key rather than blend_data_source_id.
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 type: union stacks rows, join joins data sources on shared fields.
Blend created successfully
{
"meta": {
"request_id": "RfNUgKPReZtgmzkqAFe4ArjuCQXQuaRr"
},
"data": {
"blend_id": 569,
"blend_uuid": "71bc0582-31b5-11f1-a55c-4201ac182030",
"type": "union",
"display_name": "Example Blend",
"description": "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.
Access forbidden
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "FORBIDDEN",
"message": "You do not have access to this resource."
}
}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.