Create a usage export job

Updated on Sep 4, 2026
Published on Aug 31, 2026

Post

/v1/teams/{team_id}/usage-exports

Create a usage export job for a team.

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>

Path parameters

team_id

integer (int64) Required

The team ID that owns the exports.

Minimum1

Maximum9223372036854776000

Example936506

Body parameters

The reporting period and product scope to export.

{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31",
  "product_categories": [
    "API",
    "DS"
  ],
  "license_ids": [
    100
  ]
}

object

start_date

string (date) Required

Inclusive UTC start date (Y-m-d) of the reporting period.

Max length10

Example2026-01-01

end_date

string (date) Required

Inclusive UTC end date (Y-m-d) of the reporting period.

Max length10

Example2026-01-31

product_categories

Array of string (ProductCategory) Required

Product categories to export. At least one is required.

Min items1

Max items100

Example[ "API", "DS" ]

string

A Supermetrics product category as recorded on a usage row.

Valid values[ "GADGL", "DS", "DWH_SQL_BQ", "API", "DWH_BQ", "DWH_INT_BQ", "GS", "EXCEL", "DWH_S3S", "DWH_AZS", "DWH_SNO", "CLAUDE", "DWH_GCS", "PBI", "DWH_SQL_AZR", "DWH_RSH", "STUDIO", "DWH_FTP", "DASH", "CHATGPT", "DWH_SQL_MSFBR", "XPLD", "DWH_SQL_DBR", "DWH_AZR", "DWH_SQL_ALY", "CONNECTOR_BUILDER", "GEMINI", "COPILOT", "CAPI", "STUDIO_EDIT", "DWH", "GPT", "DWH_INT", "DWH_SQL" ]

ExampleAPI

license_ids

Array of integer

Restrict the export to these license IDs.

Max items100

Example[ 100, 101 ]

integer (int64)

Minimum1

Maximum9223372036854776000

api_key_ids

Array of integer

Restrict the export to these API key IDs.

Max items100

Example[ 7 ]

integer (int64)

Minimum1

Maximum9223372036854776000

data_sources

Array of string

Restrict the export to these data source IDs.

Max items100

Example[ "GA4" ]

string

Max length5

Pattern^[A-Za-z0-9_]{2,5}$

user_ids

Array of integer

Restrict the export to these user IDs.

Max items100

Example[ 42 ]

integer (int64)

Minimum1

Maximum9223372036854776000

Responses

202

Export job accepted for processing.

Expand All

object

Response envelope for a newly accepted export job.

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

data

object (ExportCreatedOutput)

A newly accepted export job.

string (uuid)

The generated export job id.

Max length36

Example0f8fad5b-d9cb-469f-a165-70867728950e

status

string

Current status of the export job.

Valid values[ "PENDING", "RUNNING", "READY", "FAILED" ]

ExamplePENDING

requested_at

string (date-time) | null

When the export job was requested.

Max length32

Example2026-07-14T09:00:00Z

expires_at

string (date-time) | null

When the export expires; null until the job is READY.

Max length32

Example

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

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

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 Content - invalid or corrupted data

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_CONTENT",
    "message": "The content is invalid or corrupted."
  }
}

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

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

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

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.

Was this article helpful?

Documentation Index

Create a usage export job