Documentation Index

Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt

Use this file to discover all available pages before exploring further.

Get segments

  • Updated on Jul 10, 2026
  • Published on Dec 12, 2025
Prev Next
Get
/query/segments

List all available data source logins for current team and their segments

Security
HTTP
Type bearer

API key authentication. Create API keys in the Supermetrics Hub and send them in the Authorization header: Authorization: Bearer <your-api-key>

Query parameters
ds_id
stringRequired

Data source ID

Max length50
Pattern^[A-Za-z0-9_-]+$
ExampleGA
ds_users
string

Comma-separated list of usernames. Defaults to all available.

Max length100
Exampleexample
cache_minutes
integer (int32)

Maximum allowed age of the cached segments in minutes. Defaults to none for last fetched data.

Minimum60
Maximum1440
Example60
Responses
200

Segments retrieved successfully

Expand All
object

List of data source segments and metadata.

meta
object (SegmentListMetaOutput)

Metadata about the segment list.

request_id
string

API request ID

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

Query metadata including cache age.

cache_minutes
integer (int32) | null

Maximum allowed age of cached data in minutes.

Minimum60
Maximum1440
data
Array of object (SegmentListTokenOutput)

List of all segments for requested data source users.

Max items100
object

Details about a data source user and their associated segments.

ds_user
string

The data source username.

Max length255
display_name
string

Display name of the data source user.

Max length255
cache_time
string (date-time) | null

Timestamp of the last data refresh for this user.

Max length30
segments
Array of object (SegmentListSegmentOutput)

List of segments associated with this user.

Max items1000
object

Details about a specific data source segment.

segment_id
string

Unique identifier of the segment.

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

Name of the segment.

Max length255
400

Bad request - invalid parameters

Headers
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example5000
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example4999
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
{
  "meta": {
    "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
  },
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request was invalid."
  }
}
Expand All
object

Standard envelope returned by all error (4xx/5xx) responses.

meta
object (Meta)

Metadata included in every API response.

request_id
string

Unique identifier for the request, for tracking and debugging.

Min length8
Max length64
Pattern^[A-Za-z0-9_-]+$
ExampleBXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN
error
object (Error)

Machine- and human-readable detail for a failed request.

code
string

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.

Max length100
Pattern^[A-Z][A-Z0-9_]*$
ExampleBAD_REQUEST
message
string

Short, human-readable summary of the error.

Max length255
Pattern^.+$
ExampleThe request was invalid.
description
string

Optional longer explanation specific to this occurrence.

Max length2048
ExampleThe field 'display_name' must not be empty.
401

Unauthorized

Headers
WWW-Authenticate
string
Bearer token required
Max length255
Pattern^Bearer.*
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example5000
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example4999
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
{
  "meta": {
    "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
  },
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required."
  }
}
Expand All
object

Standard envelope returned by all error (4xx/5xx) responses.

meta
object (Meta)

Metadata included in every API response.

request_id
string

Unique identifier for the request, for tracking and debugging.

Min length8
Max length64
Pattern^[A-Za-z0-9_-]+$
ExampleBXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN
error
object (Error)

Machine- and human-readable detail for a failed request.

code
string

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.

Max length100
Pattern^[A-Z][A-Z0-9_]*$
ExampleBAD_REQUEST
message
string

Short, human-readable summary of the error.

Max length255
Pattern^.+$
ExampleThe request was invalid.
description
string

Optional longer explanation specific to this occurrence.

Max length2048
ExampleThe field 'display_name' must not be empty.
403

Permission denied

Headers
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example5000
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example4999
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
{
  "meta": {
    "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
  },
  "error": {
    "code": "PERMISSION_ERROR",
    "message": "You do not have permission to perform this action."
  }
}
Expand All
object

Standard envelope returned by all error (4xx/5xx) responses.

meta
object (Meta)

Metadata included in every API response.

request_id
string

Unique identifier for the request, for tracking and debugging.

Min length8
Max length64
Pattern^[A-Za-z0-9_-]+$
ExampleBXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN
error
object (Error)

Machine- and human-readable detail for a failed request.

code
string

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.

Max length100
Pattern^[A-Z][A-Z0-9_]*$
ExampleBAD_REQUEST
message
string

Short, human-readable summary of the error.

Max length255
Pattern^.+$
ExampleThe request was invalid.
description
string

Optional longer explanation specific to this occurrence.

Max length2048
ExampleThe field 'display_name' must not be empty.
422

Unprocessable Entity - validation failed for the request parameters

Headers
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example5000
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example4999
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
{
  "meta": {
    "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
  },
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Validation failed for the request parameters."
  }
}
Expand All
object

Standard envelope returned by all error (4xx/5xx) responses.

meta
object (Meta)

Metadata included in every API response.

request_id
string

Unique identifier for the request, for tracking and debugging.

Min length8
Max length64
Pattern^[A-Za-z0-9_-]+$
ExampleBXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN
error
object (Error)

Machine- and human-readable detail for a failed request.

code
string

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.

Max length100
Pattern^[A-Z][A-Z0-9_]*$
ExampleBAD_REQUEST
message
string

Short, human-readable summary of the error.

Max length255
Pattern^.+$
ExampleThe request was invalid.
description
string

Optional longer explanation specific to this occurrence.

Max length2048
ExampleThe field 'display_name' must not be empty.
429

Too Many Requests

Headers
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example5000
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example4999
Retry-After
integer
Seconds until rate limit resets
Minimum1
Maximum86400
Example3600
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
{
  "meta": {
    "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
  },
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Rate limit exceeded. Retry later."
  }
}
Expand All
object

Standard envelope returned by all error (4xx/5xx) responses.

meta
object (Meta)

Metadata included in every API response.

request_id
string

Unique identifier for the request, for tracking and debugging.

Min length8
Max length64
Pattern^[A-Za-z0-9_-]+$
ExampleBXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN
error
object (Error)

Machine- and human-readable detail for a failed request.

code
string

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.

Max length100
Pattern^[A-Z][A-Z0-9_]*$
ExampleBAD_REQUEST
message
string

Short, human-readable summary of the error.

Max length255
Pattern^.+$
ExampleThe request was invalid.
description
string

Optional longer explanation specific to this occurrence.

Max length2048
ExampleThe field 'display_name' must not be empty.
500

Internal server error

Headers
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
{
  "meta": {
    "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
  },
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred."
  }
}
Expand All
object

Standard envelope returned by all error (4xx/5xx) responses.

meta
object (Meta)

Metadata included in every API response.

request_id
string

Unique identifier for the request, for tracking and debugging.

Min length8
Max length64
Pattern^[A-Za-z0-9_-]+$
ExampleBXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN
error
object (Error)

Machine- and human-readable detail for a failed request.

code
string

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.

Max length100
Pattern^[A-Z][A-Z0-9_]*$
ExampleBAD_REQUEST
message
string

Short, human-readable summary of the error.

Max length255
Pattern^.+$
ExampleThe request was invalid.
description
string

Optional longer explanation specific to this occurrence.

Max length2048
ExampleThe field 'display_name' must not be empty.

© Supermetrics 2026