Supermetrics Documentation | Supermetrics API

Manage table groups

Manage your team's custom table groups. A table group consists a list of named tables, each containing dimensions and metrics from a data source query.

We currently support listing, exporting and importing table groups.

List table groups
Export table group
Import table group
Model version 1
Object reference
Errors

List table groups

GET https://api.supermetrics.com/enterprise/v2/table/groups

Response

Property	Type	Description
meta > request_id	string	API request ID
data	table_group[]	Table group objects

HTTP 200 OK
{
    "meta": {
        "request_id": "WnjTGeKqOXTnkZQMbZCfVMdmswv2wAzx"
    },
    "data": [
        {
            "@type": "table_group",
            "group_id": "tg_1",
            "name": "My table group"
        },
        {
            "@type": "table_group",
            "group_id": "tg_2",
            "name": "Another table group"
        }
    ]
}

Errors

TABLE_GROUP_SEARCH_FAILED

Permissions

table_groups_read

Export table group

GET https://api.supermetrics.com/enterprise/v2/table/group/:group_id/export

group_id string
Supermetrics table group ID
version int
Required. Data model version for the returned data. See supported models.

Errors

TABLE_GROUP_NOT_FOUND, TABLE_GROUP_SEARCH_FAILED

Permissions

table_groups_read

Import table group

POST https://api.supermetrics.com/enterprise/v2/table/group/import

version int
Required. Data model version for the received data. See supported models.
...
Additional properties depending on version parameter

Response

Property	Type	Description
meta > request_id	string	API request ID
data	table_group	Table group object

HTTP 201 Created
{
    "@type": "table_group",
    "group_id": "tg_1",
    "name": "My table group",
    "links": {
        "enclosure": {
            "href": "https://.../table/group/tg_1/export?version=1"
        }
    }
}

Errors

IMPORT_FIELD_ITEM_TYPE_INVALID, IMPORT_PROPERTY_TYPE_INVALID, IMPORT_TABLE_FIELD_TYPE_INVALID, IMPORT_TABLE_ITEM_TYPE_INVALID, IMPORT_VERSION_INVALID, SCHEMA_DATA_SOURCE_FIELD_NOT_FOUND, SCHEMA_DATA_SOURCE_ID_INVALID, SCHEMA_NAME_DUPLICATE, SCHEMA_NAME_REQUIRED, SCHEMA_TABLE_FIELDS_REQUIRED, SCHEMA_TABLE_NAME_REQUIRED, SCHEMA_TABLE_ORDER_OUT_OF_RANGE, SCHEMA_TABLE_PARTITION_INVALID, SCHEMA_TABLE_REPORT_TYPE_NOT_FOUND, SCHEMA_TABLE_TARGET_NAME_DUPLICATES, SCHEMA_TABLES_REQUIRED, SCHEMA_UNEXPECTED_FAILURE, TABLE_GROUP_CREATE_FAILED, TABLE_GROUP_NOT_FOUND, TABLE_GROUP_SEARCH_FAILED

Permissions

table_groups_write

Model version 1

This data model contains basic group information, tables, and fields for each table. Some additional information about each field is also given.

The export response can be sent to the import endpoint without any alteration to copy it. Read-only properties, such as field type, will simply be ignored.

Model

version	int	Always 1
group	object	Table group object
tables	object[]	Required. List of table objects
fields	object[]	Optional. List of field objects

Table group

group_id	string	Supermetrics table group ID. Read-only.
group_name	string	Required. Table group name
ds_id	string	Required. Data source ID. See data sources.
table_prefix	string	Prefix to table names. Enforced into upper snake case. Maximum length is 15 characters. Appended with an underscore. Defaults to a datasource specific value.

Table

table_name	string	Required. Table name. Enforced into upper snake case.
table_partition	string	Table partition. Either date or none. Defaults to date.
report_type	string	Conditional. Data source report type. Required for some data sources. Defaults to null.
fields	string[]	Required. List of field IDs for the table

Field

field_id	string	Required. Field ID that appears in one of the table objects
field_name	string	Data source field name. Read-only.
display_name	string	Field display name. Read-only.
target_name	string	Field name in target table. Defaults to field ID in lower snake case.
data_type	string	Field data type. Read-only. See field data types for more.

Examples

Import

POST https://api.supermetrics.com/enterprise/v2/table/group/import
Authorization: Bearer <your api key>
Content-Type: application/json

{
    "version": 1,
    "group": {
        "group_name": "My table group",
        "ds_id": "GA"
    },
    "tables": [
        {
            "table_name": "Table 1",
            "fields": [
                "date",
                "users"
            ]
        }
    ],
    "fields": [
        {
            "field_id": "users",
            "target_name": "site_users"
        }
    ]
}

Export

HTTP 200 OK
{
    "version": 1,
    "group": {
        "group_id": "tg_1",
        "group_name": "My table group",
        "ds_id": "GA",
        "table_prefix": "GA_"
    },
    "tables": [
        {
            "table_name": "TABLE_1",
            "table_partition": "date",
            "report_type": null,
            "fields": [
                "date",
                "users"
            ]
        },
        {
            "table_name": "TABLE_2",
            "table_partition": "date",
            "report_type": null,
            "fields": [
                "browser",
                "users",
                "newvisits"
            ]
        }
    ],
    "fields": [
        {
            "field_id": "date",
            "field_name": "Date",
            "display_name": "Date",
            "target_name": "date",
            "data_type": "string.time.date"
        },
        {
            "field_id": "users",
            "field_name": "Users",
            "display_name": "Users",
            "target_name": "total_users",
            "data_type": "int.number.value"
        },
        {
            "field_id": "browser",
            "field_name": "Browser",
            "display_name": "Browser",
            "target_name": "browser_name",
            "data_type": "string.text.value"
        },
        {
            "field_id": "newvisits",
            "field_name": "newvisits",
            "display_name": "New users",
            "target_name": "newvisits",
            "data_type": "int.number.value"
        }
    ]
}

Object reference

table_group

Property	Type	Description
group_id	string	Supermetrics table group ID
name	string	Table group name
links > enclosure	resource_url	Resource URL to export the table group

resource_url

Property	Type	Description
href	string	Full URL to the resource

Errors

Status	Error	Description
400	IMPORT_FIELD_ITEM_TYPE_INVALID	List of fields to import should contain only objects.
400	IMPORT_PROPERTY_TYPE_INVALID	Import property had an unexpected type.
400	IMPORT_TABLE_FIELD_TYPE_INVALID	List of table fields to import should contain only strings.
400	IMPORT_TABLE_ITEM_TYPE_INVALID	List of tables to import should contain only objects.
400	IMPORT_VERSION_INVALID	Import model version is invalid.
400	SCHEMA_DATA_SOURCE_FIELD_NOT_FOUND	Unable to find specified data source field.
400	SCHEMA_DATA_SOURCE_ID_INVALID	Provided data source ID is not valid or accessible.
409	SCHEMA_NAME_DUPLICATE	Another schema with the same name already exists.
400	SCHEMA_NAME_REQUIRED	Schema name is required.
400	SCHEMA_TABLE_FIELDS_REQUIRED	Schema table should have fields.
400	SCHEMA_TABLE_NAME_REQUIRED	Schema table should have a name.
400	SCHEMA_TABLE_ORDER_OUT_OF_RANGE	Too many tables provided for the schema.
400	SCHEMA_TABLE_PARTITION_INVALID	Schema table partition value is not supported.
400	SCHEMA_TABLE_REPORT_TYPE_NOT_FOUND	Unable to find specified report type from the data source.
400	SCHEMA_TABLE_TARGET_NAME_DUPLICATES	Multiple fields with the same target name was given.
400	SCHEMA_TABLES_REQUIRED	Schema tables are required.
500	SCHEMA_UNEXPECTED_FAILURE	Something went wrong while processing the schema. Please try again or contact support.
500	TABLE_GROUP_CREATE_FAILED	Failed to create a new table group. Please try again or contact support.
404	TABLE_GROUP_NOT_FOUND	Requested table group was not found.
500	TABLE_GROUP_SEARCH_FAILED	Something went wrong while searching for table groups. Please try again or contact support.

Last updated 2023-10-09 UTC.