Update backfill status

Updated on Mar 25, 2026
Published on Mar 2, 2026

Patch

/teams/{team_id}/backfills/{backfill_id}

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//backfills/

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

Security

HTTP

Type bearer

Bearer token authentication. Include the token in the Authorization header: Authorization: Bearer <your-token>

Path parameters

team_id

integer (int64) Required

Unique identifier of the team

Minimum1

Maximum9223372036854776000

Example12345

backfill_id

integer (int64) Required

Unique identifier of the backfill

Minimum1

Maximum9223372036854776000

Example12345

Body parameters

Status update parameters

{
  "status": "CANCELLED"
}

object

status

string Required

New status for the backfill. Currently only "CANCELLED" is supported.

Valid values[ "CANCELLED" ]

ExampleCANCELLED

Responses

200

Backfill status successfully updated

Headers

Access-Control-Allow-Origin

string

CORS header

Valid values[ "*" ]

Max length255

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": []
  }
}

Expand All

object

meta

object (ResponseMeta)

request_id

string

API request ID

Max length50

Pattern^[A-Za-z0-9_-]+$

data

object (Backfill)

transfer_backfill_id

integer (int64)

Unique identifier of the backfill

Minimum1

Maximum9223372036854776000

Example12345

transfer_id

integer (int64)

ID of the transfer this backfill belongs to

Minimum1

Maximum9223372036854776000

Example456789

range_start_date

string (date)

Start date of the backfill range

Max length10

Example2024-01-01

range_end_date

string (date)

End date of the backfill range

Max length10

Example2024-01-31

created_time

string (date-time)

Timestamp when the backfill was created (ISO 8601 format)

Max length30

Example2024-02-01T09:00:00Z

created_user_id

integer (int64)

ID of the user who created the backfill

Minimum1

Maximum9223372036854776000

Example789

removed_time

string (date-time) | null

Timestamp when the backfill was cancelled/removed (ISO 8601 format)

Max length30

Example2024-02-01T15:00:00Z

removed_user_id

integer (int64) | null

ID of the user who cancelled/removed the backfill

Minimum1

Maximum9223372036854776000

Example790

start_time

string (date-time) | null

Timestamp when the backfill processing started (ISO 8601 format)

Max length30

Example2024-02-01T10:00:00Z

end_time

string (date-time) | null

Timestamp when the backfill processing completed (ISO 8601 format)

Max length30

Example2024-02-01T12:30:00Z

status

string

Current status of the backfill

Valid values[ "CREATED", "SCHEDULED", "RUNNING", "FAILED", "COMPLETED", "CANCELLED" ]

ExampleRUNNING

transfer_runs_total

integer (int32)

Total number of transfer runs created for this backfill

Minimum0

Maximum2147483647

Example31

transfer_runs_created

integer (int32)

Number of transfer runs that have been created

Minimum0

Maximum2147483647

Example31

transfer_runs_completed

integer (int32)

Number of transfer runs that have completed successfully

Minimum0

Maximum2147483647

Example25

transfer_runs_failed

integer (int32)

Number of transfer runs that have failed

Minimum0

Maximum2147483647

Example2

error_report

Array of object (TransferBackfillRunError)

List of errors that occurred during backfill processing (empty array if no errors)

object

transfer_run_date

string (date)

The date of the transfer run that failed

Max length10

Example2024-01-15

error

string

Error message describing what went wrong

Max length1000

ExampleConnection timeout to data source

400

Bad Request - The request was invalid or cannot be served.

Headers

Access-Control-Allow-Origin

string

CORS header

Valid values[ "*" ]

Max length255

Example*

{
  "meta": {
    "request_id": "01892A4D-7586-7000-8000-000000000000"
  },
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid Parameter",
    "description": "The request contains invalid or malformed parameters."
  }
}

Expand All

object

meta

object (ResponseMeta)

request_id

string

API request ID

Max length50

Pattern^[A-Za-z0-9_-]+$

error

object (Error)

code

string

Error code

Max length100

message

string

Error message

Max length255

description

string

Error description

Max length255

401

Unauthorized - Authentication is required and has failed or has not been provided.

Headers

Access-Control-Allow-Origin

string

CORS header

Valid values[ "*" ]

Max length255

Example*

{
  "meta": {
    "request_id": "019461A0-0000-7000-8000-000000000000"
  },
  "error": {
    "code": "API_KEY_INVALID",
    "message": "Invalid API key",
    "description": "Provided API key was invalid."
  }
}

Expand All

object

meta

object (ResponseMeta)

request_id

string

API request ID

Max length50

Pattern^[A-Za-z0-9_-]+$

error

object (Error)

code

string

Error code

Max length100

message

string

Error message

Max length255

description

string

Error description

Max length255

403

Forbidden - The request is understood, but access is not allowed

Headers

Access-Control-Allow-Origin

string

CORS header

Valid values[ "*" ]

Max length255

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."
  }
}

Expand All

object

meta

object (ResponseMeta)

request_id

string

API request ID

Max length50

Pattern^[A-Za-z0-9_-]+$

error

object (Error)

code

string

Error code

Max length100

message

string

Error message

Max length255

description

string

Error description

Max length255

404

Backfill not found

Headers

Access-Control-Allow-Origin

string

CORS header

Valid values[ "*" ]

Max length255

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."
  }
}

Expand All

object

meta

object (ResponseMeta)

request_id

string

API request ID

Max length50

Pattern^[A-Za-z0-9_-]+$

error

object (Error)

code

string

Error code

Max length100

message

string

Error message

Max length255

description

string

Error description

Max length255

422

Unprocessable Entity - request validation failed

Headers

Content-Type

string

HTTP response content type

Valid values[ "application/json" ]

Max length255

Exampleapplication/json

X-RateLimit-Limit

integer

Request limit per hour

Minimum1

Maximum10000

Example100

X-RateLimit-Remaining

integer

Remaining requests in current window

Minimum0

Maximum10000

Example49

Access-Control-Allow-Origin

string

CORS header

Valid values[ "*" ]

Max length255

Example*

Expand All

object

meta

object (ResponseMeta)

request_id

string

API request ID

Max length50

Pattern^[A-Za-z0-9_-]+$

error

object (Error)

code

string

Error code

Max length100

message

string

Error message

Max length255

description

string

Error description

Max length255

429

Too Many Requests - Rate limit exceeded.

Headers

Retry-After

integer

Number of seconds to wait before making another request

Minimum1

Maximum3600

Access-Control-Allow-Origin

string

CORS header

Valid values[ "*" ]

Max length255

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."
  }
}

Expand All

object

meta

object (ResponseMeta)

request_id

string

API request ID

Max length50

Pattern^[A-Za-z0-9_-]+$

error

object (Error)

code

string

Error code

Max length100

message

string

Error message

Max length255

description

string

Error description

Max length255

500

Internal Server Error - An error occurred on the server.

Headers

Access-Control-Allow-Origin

string

CORS header

Valid values[ "*" ]

Max length255

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."
  }
}

Expand All

object

meta

object (ResponseMeta)

request_id

string

API request ID

Max length50

Pattern^[A-Za-z0-9_-]+$

error

object (Error)

code

string

Error code

Max length100

message

string

Error message

Max length255

description

string

Error description

Max length255

Was this article helpful?