Get backfill by ID

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

Get

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

Retrieve detailed information about a specific backfill using its unique identifier. This endpoint returns the complete backfill object with current status, progress tracking, and error details.

Returns: The backfill object with its ID, status, progress information, and error details if any.

Important Notes:

The backfill must exist and belong to your team
Requires scope dwh_transfers_read
Your account must have dwh.transfer.view permission. See roles and permissions.
Returns 404 if the backfill does not exist or does not belong to your team
The backfill object includes real-time progress tracking for running backfills

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

Responses

200

Backfill retrieved successfully

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,
    "start_time": "2024-02-01T10:00:00Z",
    "end_time": null,
    "status": "RUNNING",
    "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

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

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?