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

# Update backfill status

> Update the status of a backfill. Currently, the only supported operation is
cancelling a backfill by setting status to "CANCELLED".

**What happens when you cancel:**
- Backfill status is changed to "CANCELLED"
- All pending/queued transfer runs associated with this backfill are cancelled
- Transfer runs that are already running will complete
- The backfill's `end_time` is set to the cancellation time
- The `removed_time` and `removed_user_id` fields are set

**Important: This endpoint does NOT delete the backfill.**
- The backfill record remains in the system with status "CANCELLED"
- You can still retrieve the backfill information using GET /v1/teams/{team_id}/backfills/{backfill_id}

**Returns:** The updated backfill object with the new status and updated timestamps.

**Important Notes:**
- The backfill must exist and belong to your team
- Requires scope `dwh_transfers_write`
- Your account must have `dwh.transfer.edit` permission. See [roles and permissions](https://docs.supermetrics.com/docs/about-supermetrics-teams-and-user-roles#user-roles).
- Only backfills with incomplete status (CREATED, SCHEDULED, RUNNING, FAILED) can be cancelled
- Returns 404 if the backfill does not exist or does not belong to your team
- Returns 422 if the backfill cannot be updated (e.g., already in a final state)


## OpenAPI

````json PATCH /teams/{team_id}/backfills/{backfill_id}
{
  "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"
    }
  ],
  "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"
    }
  ],
  "externalDocs": {
    "description": "Find out more about Supermetrics Management API",
    "url": "https://docs.supermetrics.com/apidocs/management-api"
  },
  "paths": {
    "/teams/{team_id}/backfills/{backfill_id}": {
      "servers": [
        {
          "url": "https://dts-api.supermetrics.com/v1",
          "description": "Data Backfills API"
        }
      ],
      "patch": {
        "summary": "Update backfill status",
        "description": "Update the status of a backfill. Currently, the only supported operation is\ncancelling a backfill by setting status to \"CANCELLED\".\n\n**What happens when you cancel:**\n- Backfill status is changed to \"CANCELLED\"\n- All pending/queued transfer runs associated with this backfill are cancelled\n- Transfer runs that are already running will complete\n- The backfill's `end_time` is set to the cancellation time\n- The `removed_time` and `removed_user_id` fields are set\n\n**Important: This endpoint does NOT delete the backfill.**\n- The backfill record remains in the system with status \"CANCELLED\"\n- You can still retrieve the backfill information using GET /v1/teams/{team_id}/backfills/{backfill_id}\n\n**Returns:** The updated backfill object with the new status and updated timestamps.\n\n**Important Notes:**\n- The backfill must exist and belong to your team\n- Requires scope `dwh_transfers_write`\n- Your account must have `dwh.transfer.edit` permission. See [roles and permissions](https://docs.supermetrics.com/docs/about-supermetrics-teams-and-user-roles#user-roles).\n- Only backfills with incomplete status (CREATED, SCHEDULED, RUNNING, FAILED) can be cancelled\n- Returns 404 if the backfill does not exist or does not belong to your team\n- Returns 422 if the backfill cannot be updated (e.g., already in a final state)\n",
        "operationId": "updateBackfillStatus",
        "tags": [
          "Data Backfills"
        ],
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/DwhTeamIdPathParam"
          },
          {
            "$ref": "#/components/parameters/DwhBackfillIdPathParam"
          }
        ],
        "requestBody": {
          "required": "true",
          "description": "Status update parameters",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "description": "New status for the backfill. Currently only \"CANCELLED\" is supported.",
                    "enum": [
                      "CANCELLED"
                    ],
                    "example": "CANCELLED"
                  }
                }
              },
              "example": {
                "status": "CANCELLED"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Backfill status successfully updated",
            "headers": {
              "Access-Control-Allow-Origin": {
                "$ref": "#/components/headers/Access-Control-Allow-Origin"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BackfillResponse"
                },
                "example": {
                  "meta": {
                    "request_id": "01892A4D-7586-7000-8000-000000000000"
                  },
                  "data": {
                    "transfer_backfill_id": "12345",
                    "transfer_id": "456789",
                    "range_start_date": "2024-01-01",
                    "range_end_date": "2024-01-31",
                    "created_time": "2024-02-01T09:00:00Z",
                    "created_user_id": "789",
                    "removed_time": "2024-02-01T15:30:00Z",
                    "removed_user_id": "790",
                    "start_time": "2024-02-01T10:00:00Z",
                    "end_time": "2024-02-01T15:30:00Z",
                    "status": "CANCELLED",
                    "transfer_runs_total": "31",
                    "transfer_runs_created": "31",
                    "transfer_runs_completed": "25",
                    "transfer_runs_failed": "2",
                    "error_report": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/DwhBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/DwhUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/DwhBackfillNotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/DwhTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/DwhInternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "DwhTeamIdPathParam": {
        "name": "team_id",
        "in": "path",
        "required": "true",
        "description": "Unique identifier of the team",
        "example": "12345",
        "schema": {
          "type": "integer",
          "format": "int64",
          "minimum": "1",
          "maximum": "9223372036854776000"
        }
      },
      "DwhBackfillIdPathParam": {
        "name": "backfill_id",
        "in": "path",
        "required": "true",
        "description": "Unique identifier of the backfill",
        "example": "12345",
        "schema": {
          "type": "integer",
          "format": "int64",
          "minimum": "1",
          "maximum": "9223372036854776000"
        }
      }
    },
    "headers": {
      "Access-Control-Allow-Origin": {
        "description": "CORS header",
        "schema": {
          "type": "string",
          "maxLength": "255",
          "enum": [
            "*"
          ],
          "example": "*"
        }
      },
      "Content-Type": {
        "description": "HTTP response content type",
        "schema": {
          "type": "string",
          "maxLength": "255",
          "enum": [
            "application/json"
          ],
          "example": "application/json"
        }
      },
      "X-RateLimit-Limit": {
        "description": "Request limit per hour",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": "1",
          "maximum": "10000",
          "example": "100"
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Remaining requests in current window",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": "0",
          "maximum": "10000",
          "example": "49"
        }
      }
    },
    "schemas": {
      "BackfillResponse": {
        "type": "object",
        "required": [
          "meta",
          "data"
        ],
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "data": {
            "$ref": "#/components/schemas/Backfill"
          }
        }
      },
      "ResponseMeta": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "maxLength": "50",
            "pattern": "^[A-Za-z0-9_-]+$",
            "description": "API request ID"
          }
        }
      },
      "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"
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          },
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "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"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "maxLength": "100",
            "description": "Error code"
          },
          "message": {
            "type": "string",
            "maxLength": "255",
            "description": "Error message"
          },
          "description": {
            "type": "string",
            "maxLength": "255",
            "description": "Error description"
          }
        }
      }
    },
    "responses": {
      "DwhBadRequest": {
        "description": "Bad Request - The request was invalid or cannot be served.",
        "headers": {
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "01892A4D-7586-7000-8000-000000000000"
              },
              "error": {
                "code": "INVALID_PARAMETER",
                "message": "Invalid Parameter",
                "description": "The request contains invalid or malformed parameters."
              }
            }
          }
        }
      },
      "DwhUnauthorized": {
        "description": "Unauthorized - Authentication is required and has failed or has not been provided.",
        "headers": {
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "019461A0-0000-7000-8000-000000000000"
              },
              "error": {
                "code": "API_KEY_INVALID",
                "message": "Invalid API key",
                "description": "Provided API key was invalid."
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden - The request is understood, but access is not allowed",
        "headers": {
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "01892A4D-7586-7000-8000-000000000000"
              },
              "error": {
                "code": "ACCESS_DENIED",
                "message": "Access Denied",
                "description": "You do not have permission to perform this operation."
              }
            }
          }
        }
      },
      "DwhBackfillNotFound": {
        "description": "Backfill not found",
        "headers": {
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "01892A4D-7586-7000-8000-000000000000"
              },
              "error": {
                "code": "NOT_FOUND",
                "message": "Not Found",
                "description": "The requested backfill could not be found or you do not have access to it."
              }
            }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Unprocessable Entity - request validation failed",
        "headers": {
          "Content-Type": {
            "$ref": "#/components/headers/Content-Type"
          },
          "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"
            }
          }
        }
      },
      "DwhTooManyRequests": {
        "description": "Too Many Requests - Rate limit exceeded.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": "1",
              "maximum": "3600"
            },
            "description": "Number of seconds to wait before making another request"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "019461A0-0000-7000-8000-000000000000"
              },
              "error": {
                "code": "API_ROW_QUOTA_EXCEEDED",
                "message": "Row quota exceeded",
                "description": "You have exceeded your row-quota limit of rows for this month. Please log into Supermetrics Hub at https://hub.supermetrics.com/ and upgrade your plan, or contact our Supermetrics support team."
              }
            }
          }
        }
      },
      "DwhInternalServerError": {
        "description": "Internal Server Error - An error occurred on the server.",
        "headers": {
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/Access-Control-Allow-Origin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "meta": {
                "request_id": "01892A4D-7586-7000-8000-000000000000"
              },
              "error": {
                "code": "INTERNAL_SERVER_ERROR",
                "message": "Internal Server Error",
                "description": "An unexpected error occurred. Please try again later or contact support."
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token authentication. Include the token in the Authorization header:\n`Authorization: Bearer <your-token>`\n"
      }
    }
  }
}
````