Update backfill status

  • Updated on Mar 3, 2026
  • Published on Mar 2, 2026
Prev Next
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
  • You must have dwh.transfer.edit permission
  • 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 - 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*
object

RFC 9457 Problem Details for HTTP APIs

type
string (uri)

A URI reference that identifies the problem type

Max length255
Examplehttps://supermetrics.com/problems/unauthorized
title
string

A short, human-readable summary of the problem type

Max length255
Pattern^[A-Za-z0-9\s]+$
ExampleUnauthorized
status
integer (int32)

The HTTP status code

Minimum100
Maximum599
Example401
detail
string

A human-readable explanation specific to this occurrence

Max length1000
Pattern^[A-Za-z0-9\s.,\-]+$
ExampleAuthentication required
instance
string (uri)

A URI reference that identifies the specific occurrence

Max length255
Examplehttps://api.supermetrics.com/v2/api-keys
401

Unauthorized - invalid or missing authentication

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
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
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
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
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
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
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
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
429

Too Many Requests - rate limit exceeded

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
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*
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
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
500

Internal Server Error - unexpected server error

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
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.

© Supermetrics 2025