Update an existing table group's definition (full replace).
The request body uses the same {version, group, tables, fields} structure that Import accepts and Export returns, so the natural workflow is export → edit → PUT.
This is a full replace — all tables and fields must be provided. Omitting fields clears all field mappings. Tables and fields are matched to existing records by name. Renaming a table or field is equivalent to removing the old one and adding a new one — the old table's settings and query filter linkage are lost.
The ignore_errors and ds_settings properties are not yet supported on this endpoint and will be rejected with 422 if present.
API key authentication. Create API keys in the Supermetrics Hub and send
them in the Authorization header:
Authorization: Bearer <your-api-key>
Supermetrics table group ID (prefixed, e.g. tg_123)
Full table group definition to replace the existing one
{
"version": 1,
"group": {
"group_name": "Marketing Analytics Updated",
"ds_id": "GAWA",
"table_prefix": "MKT"
},
"tables": [
{
"table_name": "SESSIONS",
"table_partition": "date",
"fields": [
"session_id",
"date",
"users"
]
},
{
"table_name": "PAGEVIEWS",
"table_partition": "date",
"fields": [
"date",
"page_path",
"pageviews"
]
}
],
"fields": [
{
"field_id": "session_id",
"target_name": "session_id"
},
{
"field_id": "date",
"target_name": "session_date"
},
{
"field_id": "users",
"target_name": "user_count"
},
{
"field_id": "page_path",
"target_name": "page_path"
},
{
"field_id": "pageviews",
"target_name": "page_views"
}
]
}Data model version for the received data
Table group name
Data source ID
Prefix to table names. Enforced into upper snake case. Maximum length is 15 characters. Appended with an underscore.
List of table objects
Table name. Enforced into upper snake case.
Table partition. Either date or none.
Data source report type. Required for some data sources.
List of field IDs for the table
List of field objects. Omitting this property clears all field mappings (full replace).
Field ID that appears in one of the table objects
Field name in target table. Defaults to field ID in lower snake case.
Table group updated successfully
Flat response returned by import and edit endpoints.
Supermetrics table group ID (prefixed, e.g. tg_123)
Table group name
Full URL to the resource
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.
Table Group Not Found
Unprocessable Entity - validation failed for the request parameters
{
"meta": {
"request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
},
"error": {
"code": "UNPROCESSABLE_ENTITY",
"message": "Validation failed for the request parameters."
}
}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.