ArangoDB 3.11 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent stable version.

Task HTTP API

The HTTP interface for tasks lets you manage the periodic or timed execution of server-side JavaScript code

List all tasks

GET http://<EXTERNAL_ENDPOINT>:8529/_db/:database-name/_api/tasks

Fetches all existing tasks on the server.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
The list of tasks.
- array of objects
  A list of all tasks.
  command string
  The JavaScript function for this task.
  created number
  The timestamp when this task was created.
  database string
  The database this task belongs to.
  id string
  A string identifying the task.
  name string
  A user-friendly name for the task.
  offset number
  Time offset in seconds from the created timestamp.
  period number
  This task should run each period seconds.
  type string
  What type of task is this [ periodic, timed]
  periodic are tasks that repeat periodically
  timed are tasks that execute once at a specific time

Examples

Fetching all tasks

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/tasks'

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 2
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ ]

Get a task

GET http://<EXTERNAL_ENDPOINT>:8529/_db/:database-name/_api/tasks/:id

fetches one existing task on the server specified by id

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.
Example: _system
id string
The id of the task to fetch.

Query Parameters

HTTP Headers

Responses

200 OK
The requested task.
- command string
  The JavaScript function for this task.
- created number
  The timestamp when this task was created.
- database string
  The database this task belongs to.
- id string
  A string identifying the task.
- name string
  A user-friendly name for the task.
- offset number
  Time offset in seconds from the created timestamp.
- period number
  This task should run each period seconds.
- type string
  What type of task is this [ periodic, timed]
  periodic are tasks that repeat periodically
  timed are tasks that execute once at a specific time

Examples

Fetching a single task by its id

curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/tasks' <<'EOF'
{"id":"testTask","command":"console.log('Hello from task!');","offset":10000}
EOF

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/tasks/testTask'

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 206
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "id" : "testTask", 
  "name" : "user-defined task", 
  "created" : 1748024175.7621772, 
  "type" : "timed", 
  "offset" : 10000, 
  "command" : "(function (params) { console.log('Hello from task!'); } )(params);", 
  "database" : "_system" 
}

Trying to fetch a non-existing task

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/tasks/non-existing-task'

Show output

HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 73
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 404, 
  "error" : true, 
  "errorMessage" : "task not found", 
  "errorNum" : 1852 
}

Create a task

POST http://<EXTERNAL_ENDPOINT>:8529/_db/:database-name/_api/tasks

Creates a new task with a generated identifier.

Path Parameters

database-name string
The name of the database.
Example: _system

Query Parameters

HTTP Headers

Request Body application/json object

command string, required
The JavaScript code to be executed.
name string (default: "user-defined task")
The name of the task.
offset integer (default: 0)
The number of seconds for the initial delay.
params
The value to be passed to the command. It can be of any type.
period integer
The number of seconds between the executions.

Responses

200 OK
The task has been registered.
- command string
  The JavaScript code of this task.
- created number
  The timestamp when this task was created.
- database string
  The database this task belongs to.
- id string
  A string identifying the task.
- name string
  The name of the task.
- offset number
  The time offset in seconds from the created timestamp.
- period number
  The task runs every period seconds.
- type string
  Possible values: "periodic", "timed"
  The kind of the task:
  "periodic": The task repeats periodically
  "timed": The task executes once at a specific time
400 Bad Request
The task can’t be registered because the request is invalid.

Examples

curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/tasks/' <<'EOF'
{
  "name": "SampleTask",
  "command": "(function(params) { require('@arangodb').print(params); })(params)",
  "params": {
    "foo": "bar",
    "bar": "foo"
  },
  "period": 2
}
EOF

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 240
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "id" : "70151", 
  "name" : "SampleTask", 
  "created" : 1748024175.7916336, 
  "type" : "periodic", 
  "period" : 2, 
  "offset" : 0, 
  "command" : "(function (params) { (function(params) { require('@arangodb').print(params); })(params) } )(params);", 
  "database" : "_system" 
}

Create a task with ID

PUT http://<EXTERNAL_ENDPOINT>:8529/_db/:database-name/_api/tasks/:id

Registers a new task with the specified ID.

Not compatible with load balancers.

Path Parameters

database-name string
The name of the database.
Example: _system
id string
The id of the task to create

Query Parameters

HTTP Headers

Request Body application/json object

command string, required
The JavaScript code to be executed.
name string
The name of the task.
offset integer (default: 0)
The number of seconds for the initial delay.
params
The value to be passed to the command. It can be of any type.
period integer
The number of seconds between the executions.

Responses

200 OK
The task has been registered.
- command string
  The JavaScript code of this task.
- created number
  The timestamp when this task was created.
- database string
  The database this task belongs to.
- id string
  The user-provided string identifying the task.
- name string
  The name of the task.
- offset number
  The time offset in seconds from the created timestamp.
- period number
  The task runs every period seconds.
- type string
  Possible values: "periodic", "timed"
  The kind of the task:
  "periodic": The task repeats periodically
  "timed": The task executes once at a specific time
400 Bad Request
The task can’t be registered because the request is invalid.
409 Conflict
A task with the specified id already exists.

Examples

curl -X PUT --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/tasks/sampleTask' <<'EOF'
{
  "id": "SampleTask",
  "name": "SampleTask",
  "command": "(function(params) { require('@arangodb').print(params); })(params)",
  "params": {
    "foo": "bar",
    "bar": "foo"
  },
  "period": 2
}
EOF

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 245
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "id" : "sampleTask", 
  "name" : "SampleTask", 
  "created" : 1748024175.8135285, 
  "type" : "periodic", 
  "period" : 2, 
  "offset" : 0, 
  "command" : "(function (params) { (function(params) { require('@arangodb').print(params); })(params) } )(params);", 
  "database" : "_system" 
}

Delete a task

DELETE http://<EXTERNAL_ENDPOINT>:8529/_db/:database-name/_api/tasks/:id

Deletes the task identified by id on the server.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has administrate access to this database.
Example: _system
id string
The id of the task to delete.

Query Parameters

HTTP Headers

Responses

200 OK
If the task was deleted, HTTP 200 is returned.
- code integer
  The HTTP response status code.
  Example: 200
- error boolean
  false in this case
404 Not Found
If the task id is unknown, then an HTTP 404 is returned.
- code integer
  The HTTP response status code.
  Example: 404
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.

Examples

Try to delete a non-existent task:

curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/tasks/NoTaskWithThatName'

Show output

HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 73
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 404, 
  "error" : true, 
  "errorMessage" : "task not found", 
  "errorNum" : 1852 
}

Remove existing task:

curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/tasks/SampleTask'

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 26
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200 
}