Jobs#

API version: v1alpha1

DoltHub runs certain operations (merges, SQL writes, file imports) asynchronously as jobs. These endpoints let you list and inspect them.

Note: please send requests to https://www.dolthub.com, not https://dolthub.com.

List operations#

DoltHub provides support for asynchronous operations, including merging, SQL writes, and file importing. When you execute one of these operations from the API, you will get an operation name that you can poll using another endpoint to check the operation status and other information.

This API endpoint lets you monitor the status of all the operations you started in one place without needing to poll the endpoints for singular operations. These operations have error and metadata fields which contain useful information for troubleshooting and debugging.

For example, if you have executed a few SQL write queries using that API endpoint, you can list those operations using the operationType query parameter to filter for SqlWrite operations. The metadata will show the query executed, database and branch that the query ran on, as well as any syntax or other errors you may have encountered.

Here’s an example of how to list SqlWrite operations initiated by user liuliu using an authorization token.

Listing operations requires authentication, so you must include this authorization header in your request. See the Authentication section for more details.

headers = {
    'authorization': 'token [api token you created]'
}

GET /users/{username}/operations

List operations

This API endpoint allows you to list all operations that are created by the user.

URL https://www.dolthub.com/api/v1alpha1/users/{username}/operations

Parameters

Name	In	Type	Required	Description
`username`	path	string	Yes	The name of the user who initiated the operations. This user's name must match the user associated with the api token. Example: `liuliu`
`operationType`	query	string	No	Specific type of operation for this query. Supported operation types are SqlWrite, SqlRead, Import, Merge, Migrate. Example: `SqlWrite`
`pageToken`	query	string	No	Token for the next page of results Example: `AWE2Nm9uMWQ26pQQpqLNLXu7a60647lpiZoDFrf5WDGHo68XNC-rfr068rymbEdUHCXidRxx7_fwGBMSzQi6C_D50NcJFXm0BwRnGmmHEL4T4xxkWoX3sL5mKD-PuMRuxeHPsR0NB5Rzi70jGzblVlfBTIHPJ20c630pNLrI_spxH0tYTzMnQ4uPpr3ub9P50FEH9i4Au0gUkmvj8NUibbGWi-R1AJYplEPr=`

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "operations": [
    {
      "operation_name": "users/liuliu/userOperations/5e4834c9-375d-4bbd-bdaf-09eb0734127c",
      "creator": "liuliu",
      "description": "Run query CREATE TABLE tablename (\\n  pk INT,\\n  col1 VARCHAR(255),\\n  PRIMARY KEY (pk)\\n);",
      "operation_type": "SqlWrite",
      "operation_status": "liuliu",
      "error": "table with name tablename already exists",
      "metadata": "{'from_branch_name':'main','from_repo_name':'api-db','from_repo_owner':'liuliu','sql_query':'CREATE TABLE tablename (\\n  pk INT,\\n  col1 VARCHAR(255),\\n  PRIMARY KEY (pk)\\n);','to_branch_name':'main','to_repo_name':'api-db','to_repo_owner':'liuliu'}",
      "created_at": "2024-01-09T22:19:49.000Z",
      "updated_at": "2024-01-09T22:19:50.000Z"
    }
  ],
  "next_page_token": "AWE2Nm9uMWQ26pQQpqLNLXu7a60647lpiZoDFrf5WDGHo68XNC-rfr068rymbEdUHCXidRxx7_fwGBMSzQi6C_D50NcJFXm0BwRnGmmHEL4T4xxkWoX3sL5mKD-PuMRuxeHPsR0NB5Rzi70jGzblVlfBTIHPJ20c630pNLrI_spxH0tYTzMnQ4uPpr3ub9P50FEH9i4Au0gUkmvj8NUibbGWi-R1AJYplEPr="
}

Field	Type	Description
`status`	string	Status of the request.
`operations`	array<object>	List of operations
`next_page_token`	string	Token for the next page of results

400 Bad request. The request was invalid or could not be processed.

Body — application/json

{
  "status": "Error",
  "message": "Error getting the operations list.",
  "username": "liuliu",
  "operation_type": "SqlWrite"
}

Field	Type	Description
`status`	string
`message`	string
`username`	string	The name of the user who initiated the operations.
`operation_type`	string	Operation type if provided in the query

List jobs#

DoltHub performs certain asynchronous operations through job execution, including merging, importing, SQL reading, and migrating. When these operations are initiated via the API, you receive an operation name that includes the job ID.

This API endpoint lets you monitor the status of jobs started in a specific database.

Here is an example of how to list all the jobs on a database museum-collections using an authorization token.

Listing jobs requires authentication, so you must include this authorization header in your request. See the Authentication section for more details.

headers = {
    'authorization': 'token [api token you created]'
}

GET /{owner}/{database}/jobs

List jobs

This API endpoint allows you to list all jobs in your database.

URL https://www.dolthub.com/api/v1alpha1/{owner}/{database}/jobs

Parameters

Name	In	Type	Required	Description
`owner`	path	string	Yes	The name of the owner of the database. Example: `dolthub`
`database`	path	string	Yes	The name of the database. Example: `museum-collections`

Responses

200 Success

Body — application/json

{
  "status": "Success",
  "database_owner": "dolthub",
  "database_name": "museum-collections",
  "jobs": [
    {
      "job_id": "repositoryOwners/dolthub/repositories/museum-collections/jobs/aa37149c-61c3-4ce2-b3d8-694d2a152257",
      "creator": "liuliu",
      "description": "Merge pull request #9",
      "job_type": "Merge",
      "status": "Failed",
      "created_at": "2024-01-09T22:19:49.000Z",
      "error": "failed to push to branch"
    }
  ],
  "next_page_token": "AWE2Nm9uMWQ2M84_Q_ajmYOdCDIg_Ac8OuedPyAGoTT3TsBNnTSE29QPb6oJmZdbjYwdFjTwu6_ioVx4nsp3eCPoO5zyATKGsauocvy4onXjoWGfqmatl2dcm-2Ks45NPT0qRPu37HjVcaC0Qj2X5_KHcYI70fzOLn1RogexmtBlf_AtI3os4DntzhZtfp9GFtHiVekppo_26viXiKcjy0DpKay5"
}

Field	Type	Description
`status`	string	Status of the request.
`database_owner`	string	Name of the owner of the database
`database_name`	string	Name of the database
`jobs`	array<object>	List of jobs
`next_page_token`	string	Token for the next page of results

400 Bad request. The request was invalid or could not be processed.

Body — application/json

{
  "status": "Error",
  "message": "Error getting the jobs list.",
  "database_owner": "dolthub",
  "database_name": "museum-collections"
}

Field	Type	Description
`status`	string
`message`	string
`database_owner`	string	Name of the owner of the database
`database_name`	string	Name of the database