> ## 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.

# Create a usage export job

> Create a usage export job for a team.

## OpenAPI

````json POST /v1/teams/{team_id}/usage-exports
{
  "openapi": "3.0.3",
  "info": {
    "title": "Data API Reference",
    "version": "2.0.0",
    "description": "API Documentation for the Supermetrics Data API including data source search capabilities. For more information, visit https://supermetrics.com.",
    "termsOfService": "https://supermetrics.com/terms-of-service",
    "contact": {
      "name": "Supermetrics Suppot",
      "email": "support@supermetrics.com",
      "url": "https://supermetrics.com/support"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "x-api-id": "sm-data-api",
    "x-audience": "public"
  },
  "servers": [
    {
      "url": "https://api.supermetrics.com/v2",
      "description": "Global production public Supermetrics Data API base path.",
      "x-internal": false
    },
    {
      "url": "https://api.supermetrics.com",
      "description": "Global production public Supermetrics API base path for datasource search.",
      "x-internal": false
    }
  ],
  "tags": [
    {
      "name": "Get data",
      "description": "Query data and retrieve results, fields, segments, and accounts"
    },
    {
      "name": "Data Source Search",
      "description": "Search and discover data sources with filtering capabilities"
    },
    {
      "name": "Destination Search",
      "description": "Search and discover destinations for your team"
    },
    {
      "name": "API Usage",
      "description": "Retrieve API usage rollups — timeseries, top breakdowns, errors, and summary"
    },
    {
      "name": "Raw Usage Data Export",
      "description": "Endpoints for creating and retrieving a team's raw usage reposts."
    },
    {
      "name": "Campaign Management",
      "description": "Create, update, and manage advertising campaigns, audiences, conversions, keywords, and related assets"
    }
  ],
  "externalDocs": {
    "description": "Find out more about Supermetrics Data API",
    "url": "https://docs.supermetrics.com/apidocs/data-api"
  },
  "paths": {
    "/v1/teams/{team_id}/usage-exports": {
      "servers": [
        {
          "url": "https://api.supermetrics.com",
          "description": "production server",
          "x-internal": false
        }
      ],
      "post": {
        "summary": "Create a usage export job",
        "description": "Create a usage export job for a team.",
        "operationId": "create",
        "parameters": [
          {
            "in": "path",
            "name": "team_id",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "maximum": 9.223372036854776E+18
            },
            "description": "The team ID that owns the exports.",
            "example": 936506
          }
        ],
        "requestBody": {
          "required": true,
          "description": "The reporting period and product scope to export.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "start_date": {
                    "type": "string",
                    "format": "date",
                    "maxLength": 10,
                    "description": "Inclusive UTC start date (Y-m-d) of the reporting period.",
                    "example": "2026-01-01"
                  },
                  "end_date": {
                    "type": "string",
                    "format": "date",
                    "maxLength": 10,
                    "description": "Inclusive UTC end date (Y-m-d) of the reporting period.",
                    "example": "2026-01-31"
                  },
                  "product_categories": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "description": "Product categories to export. At least one is required.",
                    "items": {
                      "$ref": "#/components/schemas/ProductCategory"
                    },
                    "example": [
                      "API",
                      "DS"
                    ]
                  },
                  "license_ids": {
                    "type": "array",
                    "maxItems": 100,
                    "description": "Restrict the export to these license IDs.",
                    "items": {
                      "type": "integer",
                      "format": "int64",
                      "minimum": 1,
                      "maximum": 9.223372036854776E+18
                    },
                    "example": [
                      100,
                      101
                    ]
                  },
                  "api_key_ids": {
                    "type": "array",
                    "maxItems": 100,
                    "description": "Restrict the export to these API key IDs.",
                    "items": {
                      "type": "integer",
                      "format": "int64",
                      "minimum": 1,
                      "maximum": 9.223372036854776E+18
                    },
                    "example": [
                      7
                    ]
                  },
                  "data_sources": {
                    "type": "array",
                    "maxItems": 100,
                    "description": "Restrict the export to these data source IDs.",
                    "items": {
                      "type": "string",
                      "maxLength": 5,
                      "pattern": "^[A-Za-z0-9_]{2,5}$"
                    },
                    "example": [
                      "GA4"
                    ]
                  },
                  "user_ids": {
                    "type": "array",
                    "maxItems": 100,
                    "description": "Restrict the export to these user IDs.",
                    "items": {
                      "type": "integer",
                      "format": "int64",
                      "minimum": 1,
                      "maximum": 9.223372036854776E+18
                    },
                    "example": [
                      42
                    ]
                  }
                },
                "required": [
                  "start_date",
                  "end_date",
                  "product_categories"
                ]
              },
              "example": {
                "start_date": "2026-01-01",
                "end_date": "2026-01-31",
                "product_categories": [
                  "API",
                  "DS"
                ],
                "license_ids": [
                  100
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Export job accepted for processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExportCreatedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/PermissionDenied"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableContent"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "security": [
          {
            "ApiKeyAuth": [
              "usage_export_write"
            ]
          }
        ],
        "tags": [
          "Raw Usage Data Export"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ProductCategory": {
        "type": "string",
        "enum": [
          "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"
        ],
        "description": "A Supermetrics product category as recorded on a usage row.",
        "example": "API"
      },
      "ExportCreatedResponse": {
        "type": "object",
        "additionalProperties": false,
        "description": "Response envelope for a newly accepted export job.",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "data": {
            "$ref": "#/components/schemas/ExportCreatedOutput"
          }
        },
        "required": [
          "meta",
          "data"
        ]
      },
      "Meta": {
        "type": "object",
        "description": "Metadata included in every API response.",
        "properties": {
          "request_id": {
            "$ref": "#/components/schemas/RequestId"
          }
        },
        "required": [
          "request_id"
        ],
        "additionalProperties": false
      },
      "ExportCreatedOutput": {
        "type": "object",
        "additionalProperties": false,
        "description": "A newly accepted export job.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "maxLength": 36,
            "description": "The generated export job id.",
            "example": "0f8fad5b-d9cb-469f-a165-70867728950e"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "RUNNING",
              "READY",
              "FAILED"
            ],
            "description": "Current status of the export job.",
            "example": "PENDING"
          },
          "requested_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "maxLength": 32,
            "description": "When the export job was requested.",
            "example": "2026-07-14T09:00:00Z"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "maxLength": 32,
            "description": "When the export expires; null until the job is READY.",
            "example": null
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard envelope returned by all error (4xx/5xx) responses.",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        },
        "required": [
          "meta",
          "error"
        ],
        "additionalProperties": false
      },
      "RequestId": {
        "type": "string",
        "description": "Unique identifier for the request, for tracking and debugging.",
        "pattern": "^[A-Za-z0-9_-]+$",
        "minLength": 8,
        "maxLength": 64,
        "example": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN",
        "x-faker": {
          "random.alphaNumeric": 30
        }
      },
      "Error": {
        "type": "object",
        "description": "Machine- and human-readable detail for a failed request.",
        "properties": {
          "code": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]*$",
            "maxLength": 100,
            "description": "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.",
            "example": "BAD_REQUEST"
          },
          "message": {
            "type": "string",
            "maxLength": 255,
            "pattern": "^.+$",
            "description": "Short, human-readable summary of the error.",
            "example": "The request was invalid."
          },
          "description": {
            "type": "string",
            "maxLength": 2048,
            "description": "Optional longer explanation specific to this occurrence.",
            "example": "The field 'display_name' must not be empty."
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request - invalid parameters",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "BAD_REQUEST",
                "message": "The request was invalid."
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized",
        "headers": {
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WWW-Authenticate"
          },
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "UNAUTHORIZED",
                "message": "Authentication is required."
              }
            }
          }
        }
      },
      "PermissionDenied": {
        "description": "Permission denied",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "PERMISSION_ERROR",
                "message": "You do not have permission to perform this action."
              }
            }
          }
        }
      },
      "UnprocessableContent": {
        "description": "Unprocessable Content - invalid or corrupted data",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "UNPROCESSABLE_CONTENT",
                "message": "The content is invalid or corrupted."
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests",
        "headers": {
          "X-RateLimit-Limit": {
            "$ref": "#/components/headers/X-RateLimit-Limit"
          },
          "X-RateLimit-Remaining": {
            "$ref": "#/components/headers/X-RateLimit-Remaining"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "TOO_MANY_REQUESTS",
                "message": "Rate limit exceeded. Retry later."
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal server error",
        "headers": {
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "BXaEFVtjc7TXaJxgZhmFgSUD9edqq_CN"
              },
              "error": {
                "code": "INTERNAL_SERVER_ERROR",
                "message": "An unexpected error occurred."
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API_KEY",
        "description": "API key authentication. Create API keys in the Supermetrics Hub and send\nthem in the Authorization header:\n`Authorization: Bearer <your-api-key>`\n"
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "description": "Request limit per hour",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 10000,
          "example": 5000
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Remaining requests in current window",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 0,
          "maximum": 10000,
          "example": 4999
        }
      },
      "Access-Control-Allow-Origin": {
        "description": "CORS header",
        "schema": {
          "type": "string",
          "maxLength": 255,
          "enum": [
            "*"
          ],
          "example": "*"
        }
      },
      "WWW-Authenticate": {
        "description": "Bearer token required",
        "schema": {
          "type": "string",
          "maxLength": 255,
          "pattern": "^Bearer.*"
        }
      },
      "Retry-After": {
        "description": "Seconds until rate limit resets",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 86400,
          "example": 3600
        }
      }
    }
  }
}
````