Metavault API - Get background task

GetBackgroundTask - GET

Path	/api/projects/{projectId}/tasks/{taskId}
Http Method	GET

Overview

Retrieve information about a running background task. Background tasks are long-running processes that the front-end typically polls the status of, and retrieves a result asynchronously for. Deploying a version of the data vault model to an environment database is a background task, for example.

You cannot create a background task explicitly, some API calls are simply asynchronous and will return a task id.

Background tasks operate with the access rights of the user that created them. Task ids should therefore not be shared as they could leak information other people may not have access to. Tasks results remain available for 1 hour.

Required permissions

None

Request

Path parameters

Parameter	Type	Required	Description	Example
taskId	string	Yes	The id of the task, generated by the app on task creation.	`099ec495a1b548efa43b15da09262c20`

Response

Success response (200 OK)

JSON

{
  "id": "6151702ebe4d47ca8e4293638eafeab2",
  "status": "Waiting",
  "type": "Info",
  "creationDate": "2026-04-17T14:30:02.3313845Z",
  "lastUpdateDate": "2026-04-17T14:30:02.3313846Z",
  "userName": "Bob Marley"
}

Response fields

Field	Type	Description
id	string	The id of the Task generated by the app.
status	string	The status of the task. One of: Waiting: The task is created, and is waiting for a chance to run. A task typically does not stay in this state for long. Running: The task is currently running. Success: The task finished successfully. A result may be available. Failed: The task finished with an error. Cancelled: Happens when Metavault is shut down before having a chance to run this task.
type	string	The type of task that is run. Different asynchronous API calls generate background tasks of different types. Different types of background tasks will produce different results using the `GetBackgroundTaskResult` API call.
creationDate	string	Date and time at which this task was created.
lastUpdateDate	string	Last date and time when this task was updated.
userName	string	Name of the user that generated this task.
error	string	The error message when a task finishes with a failure.

Response links and embedded objects

Name	Link	Constraints
result