Create team list

  • Updated on Dec 15, 2025
  • Published on Sep 2, 2025
Prev Next
Post
/team/list

Create a new team list

Security
HTTP
Type bearer

Bearer token authentication. Include the token in the Authorization header: Authorization: Bearer <your-token>

Body parameters

Team list creation parameters including identifier, name, and type configuration

{
  "list_slug": "marketing_accounts",
  "list_name": "Marketing Team Account IDs",
  "list_type": "account_ids",
  "ds_id": "GAWA",
  "show_in_products": [
    "API",
    "DWH"
  ]
}
object
list_slug
string Required

User-defined ID, used to reference list in queries. Restricted to characters A-Z, a-z, 0-9 and _.

Max length50
Pattern^[A-Za-z0-9_]+$
list_name
string Required

List name, used in product UI.

Max length255
list_type
string Required

List type.

Valid values[ "account_ids" ]
ds_id
string

Data source ID. If not provided or empty string, list is global and available for all data sources.

Max length50
Pattern^[A-Za-z0-9_-]+$
show_in_products

List of Supermetrics products this list should be shown in. If not provided or empty list, not shown in any product.

OneOf
string
string
Valid values[ "API", "DWH", "MND" ]
array
array
string
Valid values[ "API", "DWH", "MND" ]
Responses
201

Team list created successfully

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
Location
string
API URL of the created item
Max length255
Exampleitems/{id}
Expand All
object
meta
object (ResponseMeta)
request_id
string

API request ID

Max length50
Pattern^[A-Za-z0-9_-]+$
data
object (TeamList)
list_id
string

Supermetrics list ID

Max length50
list_slug
string

User-defined ID, used to reference list in queries

Max length50
list_name
string

List name

Max length255
list_type
string

List type

Valid values[ "account_ids" ]
Max length50
ds_id
string

Data source ID. Empty string when list is global.

Max length50
ds_name
string

Data source name. Empty string when list is global.

Max length255
show_in_products
Array of string

List of Supermetrics products this list should be shown in. If empty, not shown in any product.

Max items100
string
Valid values[ "API", "DWH", "MND" ]
Max length100
400

List Slug Invalid

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
object
error
string
Valid values[ "LIST_SLUG_INVALID" ]
Max length100
message
string
Max length255
401

Unauthorized - invalid or missing authentication

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
Expand All
object
meta
object (ResponseMeta)
request_id
string

API request ID

Max length50
Pattern^[A-Za-z0-9_-]+$
error
object (Error)
code
string

Error code

Max length100
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
409

Team list slug conflict

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
OneOf
ListSlugExistsError
object (ListSlugExistsError)
error
string

Team list slug already exists for specified data source ID

Valid values[ "LIST_SLUG_EXISTS" ]
Max length100
message
string
Max length255
ListSlugReservedError
object (ListSlugReservedError)
error
string

Team list slug is reserved for system use

Valid values[ "LIST_SLUG_RESERVED" ]
Max length100
message
string
Max length255
422

Unprocessable Entity - request validation failed

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
Expand All
object
meta
object (ResponseMeta)
request_id
string

API request ID

Max length50
Pattern^[A-Za-z0-9_-]+$
error
object (Error)
code
string

Error code

Max length100
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
429

Too Many Requests - rate limit exceeded

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Retry-After
integer
Number of seconds to wait before making another request
Minimum1
Maximum3600
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
Expand All
object
meta
object (ResponseMeta)
request_id
string

API request ID

Max length50
Pattern^[A-Za-z0-9_-]+$
error
object (Error)
code
string

Error code

Max length100
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
500

List Create Failed

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
object
error
string
Valid values[ "LIST_CREATE_FAILED" ]
Max length100
message
string
Max length255