> ## 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. # List incomplete backfills for team > Retrieve a list of all incomplete backfills for your team. This endpoint returns only backfills that are not yet finished. **What are "incomplete" backfills?** - **Included:** Backfills with status `CREATED`, `SCHEDULED`, `RUNNING`, or `FAILED` - **Excluded:** Backfills with status `COMPLETED` or `CANCELLED` **Returns:** Array of backfill objects sorted by creation time (newest first). **Important Notes:** - Requires scope `dwh_transfers_read` - Your account must have `dwh.transfer.view` permission. See [roles and permissions](https://docs.supermetrics.com/docs/about-supermetrics-teams-and-user-roles#user-roles). - Only backfills belonging to your team are returned - The list includes backfills for all transfers in your team - Each backfill includes real-time progress tracking for running backfills ## OpenAPI ````json GET /teams/{team_id}/backfills { "openapi": "3.0.3", "info": { "title": "Management API Reference", "version": "2.0.0", "description": "API Documentation for the Supermetrics Management API. 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-management-api", "x-audience": "public" }, "servers": [ { "url": "https://api.supermetrics.com/v2", "description": "Global production public Supermetrics Management API base path.", "x-internal": "false" }, { "url": "https://api.supermetrics.com", "description": "Global production public Supermetrics API base path (for Connector Builder and Team endpoints).", "x-internal": "false" } ], "tags": [ { "name": "API Keys", "description": "Manage API keys to access Supermetrics API" }, { "name": "Data Source Logins", "description": "Access your data source authentications" }, { "name": "Data Source Login Links", "description": "Create single-use data source login links" }, { "name": "Saved Queries", "description": "Manage queries saved in Query Manager" }, { "name": "Table Groups", "description": "Manage your team's table groups" }, { "name": "Team Lists", "description": "Manage centralized team lists for your queries" }, { "name": "Team Settings", "description": "Configure general settings for your team" }, { "name": "Data Transfers", "description": "Create, configure, and manage Data Warehouse transfers" }, { "name": "Transfer Runs", "description": "Monitor execution history of Data Warehouse transfers" }, { "name": "Data Backfills", "description": "Manage historical data backfills for your Data Warehouse transfers" }, { "name": "Data Destinations", "description": "Create, configure, and manage Data Warehouse destinations" }, { "name": "Data Source Connections", "description": "Create and manage data source connections for Data Warehouse transfers" }, { "name": "Data Blending", "description": "Create and manage Data Blending" }, { "name": "Custom Fields", "description": "Create and manage Custom Fields" }, { "name": "Connectors", "description": "Create and manage custom connectors" }, { "name": "Connector Secrets", "description": "Manage encrypted secrets for connectors" }, { "name": "Connector Logs", "description": "Access connector execution logs" }, { "name": "Connector Logo", "description": "Manage connector logos" }, { "name": "Connector Schema", "description": "Retrieve connector configuration schemas" }, { "name": "Datasource", "description": "Retrieve datasource configuration details" } ], "externalDocs": { "description": "Find out more about Supermetrics Management API", "url": "https://docs.supermetrics.com/apidocs/management-api" }, "paths": { "/teams/{team_id}/backfills": { "servers": [ { "url": "https://dts-api.supermetrics.com/v1", "description": "Data Backfills API" } ], "get": { "summary": "List incomplete backfills for team", "description": "Retrieve a list of all incomplete backfills for your team.\nThis endpoint returns only backfills that are not yet finished.\n\n**What are \"incomplete\" backfills?**\n- **Included:** Backfills with status `CREATED`, `SCHEDULED`, `RUNNING`, or `FAILED`\n- **Excluded:** Backfills with status `COMPLETED` or `CANCELLED`\n\n**Returns:** Array of backfill objects sorted by creation time (newest first).\n\n**Important Notes:**\n- Requires scope `dwh_transfers_read`\n- Your account must have `dwh.transfer.view` permission. See [roles and permissions](https://docs.supermetrics.com/docs/about-supermetrics-teams-and-user-roles#user-roles).\n- Only backfills belonging to your team are returned\n- The list includes backfills for all transfers in your team\n- Each backfill includes real-time progress tracking for running backfills\n", "operationId": "listIncompleteBackfills", "tags": [ "Data Backfills" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/TeamId" } ], "responses": { "200": { "description": "List of incomplete backfills retrieved successfully", "headers": { "Access-Control-Allow-Origin": { "$ref": "#/components/headers/Access-Control-Allow-Origin" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "array", "maxItems": "100", "items": { "$ref": "#/components/schemas/Backfill" }, "description": "Array of incomplete backfill objects" } } }, "examples": { "multipleBackfills": { "summary": "Multiple incomplete backfills", "value": { "meta": { "request_id": "01892A4D-7586-7000-8000-000000000000" }, "data": [ { "transfer_backfill_id": "12347", "transfer_id": "456790", "range_start_date": "2024-02-01", "range_end_date": "2024-02-28", "created_time": "2024-03-01T14:00:00Z", "created_user_id": "789", "start_time": "2024-03-01T14:30:00Z", "end_time": null, "status": "RUNNING", "transfer_runs_total": "28", "transfer_runs_created": "28", "transfer_runs_completed": "15", "transfer_runs_failed": "0", "error_report": [] }, { "transfer_backfill_id": "12346", "transfer_id": "456789", "range_start_date": "2024-01-15", "range_end_date": "2024-01-31", "created_time": "2024-02-15T09:30:00Z", "created_user_id": "790", "start_time": "2024-02-15T10:00:00Z", "end_time": null, "status": "RUNNING", "transfer_runs_total": "17", "transfer_runs_created": "17", "transfer_runs_completed": "10", "transfer_runs_failed": "0", "error_report": [] }, { "transfer_backfill_id": "12345", "transfer_id": "456788", "range_start_date": "2024-01-01", "range_end_date": "2024-01-14", "created_time": "2024-02-01T08:00:00Z", "created_user_id": "789", "start_time": null, "end_time": null, "status": "SCHEDULED", "transfer_runs_total": "14", "transfer_runs_created": "14", "transfer_runs_completed": "0", "transfer_runs_failed": "0", "error_report": [] } ] } }, "emptyList": { "summary": "No incomplete backfills", "value": { "meta": { "request_id": "01892A4D-7586-7000-8000-000000000000" }, "data": [] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "parameters": { "TeamId": { "name": "team_id", "in": "path", "description": "ID of the team", "required": "true", "schema": { "type": "integer", "format": "int64", "minimum": "1", "maximum": "9223372036854776000" }, "example": "936506" } }, "headers": { "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.*" } }, "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" } }, "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer", "format": "int32", "minimum": "1", "maximum": "86400", "example": "3600" } } }, "schemas": { "Meta": { "type": "object", "description": "Metadata included in every API response.", "properties": { "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "request_id" ], "additionalProperties": "false" }, "Backfill": { "type": "object", "required": [ "transfer_backfill_id", "transfer_id", "range_start_date", "range_end_date", "status", "created_time", "created_user_id", "transfer_runs_total", "transfer_runs_created", "transfer_runs_completed", "transfer_runs_failed" ], "properties": { "transfer_backfill_id": { "type": "integer", "format": "int64", "minimum": "1", "maximum": "9223372036854776000", "description": "Unique identifier of the backfill", "example": "12345" }, "transfer_id": { "type": "integer", "format": "int64", "minimum": "1", "maximum": "9223372036854776000", "description": "ID of the transfer this backfill belongs to", "example": "456789" }, "range_start_date": { "type": "string", "format": "date", "maxLength": "10", "description": "Start date of the backfill range", "example": "2024-01-01" }, "range_end_date": { "type": "string", "format": "date", "maxLength": "10", "description": "End date of the backfill range", "example": "2024-01-31" }, "created_time": { "type": "string", "format": "date-time", "maxLength": "30", "description": "Timestamp when the backfill was created (ISO 8601 format)", "example": "2024-02-01T09:00:00Z" }, "created_user_id": { "type": "integer", "format": "int64", "minimum": "1", "maximum": "9223372036854776000", "description": "ID of the user who created the backfill", "example": "789" }, "removed_time": { "type": "string", "format": "date-time", "maxLength": "30", "description": "Timestamp when the backfill was cancelled/removed (ISO 8601 format)", "example": "2024-02-01T15:00:00Z", "nullable": "true" }, "removed_user_id": { "type": "integer", "format": "int64", "minimum": "1", "maximum": "9223372036854776000", "description": "ID of the user who cancelled/removed the backfill", "example": "790", "nullable": "true" }, "start_time": { "type": "string", "format": "date-time", "maxLength": "30", "description": "Timestamp when the backfill processing started (ISO 8601 format)", "example": "2024-02-01T10:00:00Z", "nullable": "true" }, "end_time": { "type": "string", "format": "date-time", "maxLength": "30", "description": "Timestamp when the backfill processing completed (ISO 8601 format)", "example": "2024-02-01T12:30:00Z", "nullable": "true" }, "status": { "type": "string", "description": "Current status of the backfill", "enum": [ "CREATED", "SCHEDULED", "RUNNING", "FAILED", "COMPLETED", "CANCELLED" ], "example": "RUNNING" }, "transfer_runs_total": { "type": "integer", "format": "int32", "minimum": "0", "maximum": "2147483647", "description": "Total number of transfer runs created for this backfill", "example": "31" }, "transfer_runs_created": { "type": "integer", "format": "int32", "minimum": "0", "maximum": "2147483647", "description": "Number of transfer runs that have been created", "example": "31" }, "transfer_runs_completed": { "type": "integer", "format": "int32", "minimum": "0", "maximum": "2147483647", "description": "Number of transfer runs that have completed successfully", "example": "25" }, "transfer_runs_failed": { "type": "integer", "format": "int32", "minimum": "0", "maximum": "2147483647", "description": "Number of transfer runs that have failed", "example": "2" }, "error_report": { "type": "array", "description": "List of errors that occurred during backfill processing (empty array if no errors)", "items": { "$ref": "#/components/schemas/TransferBackfillRunError" } } } }, "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" } }, "TransferBackfillRunError": { "type": "object", "required": [ "transfer_run_date", "error" ], "properties": { "transfer_run_date": { "type": "string", "format": "date", "maxLength": "10", "description": "The date of the transfer run that failed", "example": "2024-01-15" }, "error": { "type": "string", "maxLength": "1000", "description": "Error message describing what went wrong", "example": "Connection timeout to data source" } } }, "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" }, "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": { "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." } } } } }, "Forbidden": { "description": "Access forbidden", "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": "FORBIDDEN", "message": "You do not have access to this resource." } } } } }, "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": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "otok", "description": "Bearer token authentication. Include the token in the Authorization header:\n`Authorization: Bearer `\n" } } } } ````