API docs by Redocly

PanDA API (1.0.0)

Download OpenAPI specification:Download

HTTP methods:

  • GET: Retrieve data from the server. Parameters have to be sent in the URL.
  • PUT: Update data on the server. Parameters have to be sent in the body in json encoded format. When the client wants to gzip the data, the content encoding has to be set accordingly.

Response formats:

The return codes are usually specified with each API function, but in general:

  • 200: Function called correctly and response will be Content-type: application/json. This does not necessarily mean that the operation was successful, but that the function was called correctly. Reasons why the operation could fail are:
    • Wrong parameters or the JSON could not be decoded.
    • The function was called using the wrong HTTP method (e.g. GET instead of PUT).
    • The function expects authentication (certificate/token) and it was not provided.
    • The function expects production role and it was not provided.
    • Caught exceptions when interacting with the database.

The usual response dictionary has the following format:

{ "success": True/False, "message": "Usually an error when there was a failure. The message can generally be ignored if the operation was successful.", "response": "The data returned if the operation was successful." }
  • 403: Forbidden. The client called a forbidden function or there was an authentication issue. The response will use Content-type: text/plain.
  • 500: Server crashed calling the method. The response will use Content-type: text/plain.
  • 503: The server is overloaded. The call did not reach PanDA and the response comes from directly httpd.

harvester

Operations related to harvester

Update workers.

Update the details for a list of workers. Requires a secure connection.

Request Body schema: application/json
required
harvester_id
required
string

harvester id, e.g. harvester_central_A

workers
required
Array of objects

list of worker dictionaries that describe the fields of a pandaserver/taskbuffer/WorkerSpec object.

[{"workerID": 1, "batchID": 1, "queueName": "queue1", "status": "running",
"computingSite": "site1", "nCore": 1, "nodeID": None,
"submitTime": "02-NOV-24 00:02:18", "startTime": "02-NOV-24 00:02:18", "endTime": None,
"jobType": "managed", "resourceType": "SCORE", "nativeExitCode": None, "nativeStatus": None,
"diagMessage": None, "nJobs": 1, "computingElement": "ce1", "syncLevel": 0,
"submissionHost": "submissionhost1", "harvesterHost": "harvesterhost1",
"errorCode": None, "minRamCount": 2000},...]

Responses

Request samples

Content type
application/json
{
  • "harvester_id": "string",
  • "workers": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Update harvester service metrics.

Update the service metrics for a harvester instance. Requires a secure connection.

Request Body schema: application/json
required
harvester_id
required
string

harvester id, e.g. harvester_central_A

metrics
required
Array of objects

list of triplets [[host, timestamp, metric_dict],[host, timestamp, metric_dict]...]. The metric dictionary is json encoded, as it is stored in the database like that.

harvester_host = "harvester_host.cern.ch"
creation_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")
metric = {
    "rss_mib": 2737.36,
    "memory_pc": 39.19,
    "cpu_pc": 15.23,
    "volume_data_pc": 20.0,
    "cert_lifetime": {
        "/data/atlpan/proxy/x509up_u25606_prod": 81,
        "/data/atlpan/proxy/x509up_u25606_pilot": 81,
        "/cephfs/atlpan/harvester/proxy/x509up_u25606_prod": 96,
        "/cephfs/atlpan/harvester/proxy/x509up_u25606_pilot": 96,
    },
}

# DBProxy expects the metrics in json format and stores them directly in the database
metrics = [[creation_time, harvester_host, json.dumps(metric)]]

Responses

Request samples

Content type
application/json
{
  • "harvester_id": "string",
  • "metrics": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Heartbeat for harvester.

Send a heartbeat for harvester and optionally update the instance data. User and host are retrieved from the request object and updated in the database. Requires a secure connection.

Request Body schema: application/json
required
harvester_id
required
string

harvester id, e.g. harvester_central_A

data
required
Array of objects

list of data to be updated in the PanDA database

Responses

Request samples

Content type
application/json
{
  • "harvester_id": "string",
  • "data": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Get the current worker ID.

Retrieve the current worker ID.

query Parameters
harvester_id
required
string

harvester id, e.g. harvester_central_A

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Get worker statistics.

Get statistics for all the workers managed across the Grid.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Report worker statistics.

Report statistics for the workers managed by a harvester instance at a PanDA queue. Requires a secure connection.

Request Body schema: application/json
required
harvester_id
required
string

harvester id, e.g. harvester_central_A

panda_queue
required
string

Name of the PanDA queue, e.g. CERN.

statistics
required
string

JSON string containing a dictionary with the statistics to be reported. It will be stored as a json in the database. E.g.

json.dumps({"user": {"SCORE": {"running": 1, "submitted": 1}}, "managed": {"MCORE": {"running": 1, "submitted": 1}}})

Responses

Request samples

Content type
application/json
{
  • "harvester_id": "string",
  • "panda_queue": "string",
  • "statistics": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Get harvester commands.

Retrieves the commands for a specified harvester instance. Requires a secure connection and production role.

query Parameters
harvester_id
required
string

harvester id, e.g. harvester_central_A

n_commands
required
string

The number of commands to retrieve, e.g. 10.

timeout
string

The timeout value. Defaults to 30.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Acknowledge harvester commands.

Acknowledges the list of command IDs in the PanDA database. Requires a secure connection and production role.

query Parameters
command_ids
required
string

A list of command IDs to acknowledge, e.g. [1, 2, 3, 4,...].

timeout
string

The timeout value. Defaults to 30.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Add sweep command for harvester.

Send a command to harvester to kill the workers in a PanDA queue, with the possibility of specifying filters by status, CE or submission host. Requires a secure connection and production role.

Request Body schema: application/json
required
panda_queue
required
string

Name of the PanDA queue, e.g. CERN.

status_list
required
Array of objects

list of worker statuses to be considered, e.g. ['submitted', 'running']

ce_list
required
Array of objects

list of the Computing Elements to be considered, e.g. ['ce1.cern.ch', 'ce2.cern.ch']

submission_host_list
required
Array of objects

list of the harvester submission hosts to be considered, e.g. ['submission_host1.cern.ch', 'submission_host2.cern.ch']

Responses

Request samples

Content type
application/json
{
  • "panda_queue": "string",
  • "status_list": [
    ],
  • "ce_list": [
    ],
  • "submission_host_list": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Set target slots.

Set the target number of slots for a PanDA queue, when you want to build up job pressure. Requires secure connection and production role.

Request Body schema: application/json
required
panda_queue
required
string

Name of the PanDA queue, e.g. CERN.

slots
required
integer

Number of slots to set, e.g. 10000.

global_share
string

Global share the slots apply to. Optional - by default it applies to the whole queue. E.g. User Analysis

resource_type
string

Resource type the slots apply to. Optional - by default it applies to the whole queue. E.g. SCORE or MCORE.

expiration_date
string

The expiration date of the slots. Optional - by default it applies indefinitely.

Responses

Request samples

Content type
application/json
{
  • "panda_queue": "string",
  • "slots": 0,
  • "global_share": "string",
  • "resource_type": "string",
  • "expiration_date": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

task

Operations related to task

Retry a given task. Requires a secure connection without a production role to retry own tasks and with a production role to retry others' tasks.

Request Body schema: application/json
required
jedi_task_id
required
integer

JEDI Task ID

new_parameters
required
string

a json string of new parameters the task uses when rerunning

no_child_retry
required
boolean

if True, the child tasks are not retried

disable_staging_mode
required
boolean

if True, the task skips staging state and directly goes to subsequent state

keep_gshare_priority
required
boolean

if True, the task keeps current gshare and priority

Responses

Request samples

Content type
application/json
{
  • "jedi_task_id": 0,
  • "new_parameters": "string",
  • "no_child_retry": true,
  • "disable_staging_mode": true,
  • "keep_gshare_priority": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Enable job cloning for a given task. Requires secure connection and production role.

Request Body schema: application/json
required
jedi_task_id
required
integer

JEDI Task ID

mode
required
string

mode of operation, runonce or storeonce

multiplicity
required
integer

number of clones to be created for each target

num_sites
required
integer

number of sites to be used for each target

Responses

Request samples

Content type
application/json
{
  • "jedi_task_id": 0,
  • "mode": "string",
  • "multiplicity": 0,
  • "num_sites": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}

Disable job cloning for a given task. Requires secure connection and production role.

Request Body schema: application/json
required
jedi_task_id
required
integer

JEDI Task ID

Responses

Request samples

Content type
application/json
{
  • "jedi_task_id": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "response": { }
}