Endpoints for interacting with the Xpress Executor component, scheduling executions, querying status & results.
DELETE /runtime/execution
Delete all of the executions currently in the repository.
Response codes indicate the following:
- 200 OK: The executions list is returned (will contain only executions that could not be deleted, or were scheduled during deletion)
- 500 Internal Server Error: Unexpected failure within component
Response Body
| media type |
data type |
description |
| application/json |
array of ModelExecution (JSON) |
A JSON array of structures describing the current status of the surviving executions, in order of creation. |
Example
Request
DELETE /runtime/execution
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 204 No Content
Content-Type: application/json
[ {
"id" : "...",
"status" : "INTERNAL_ERROR",
"exitCode" : 12345,
"progress" : 12345.0,
"creation" : 12345,
"start" : 12345,
"finish" : 12345,
"parameters" : {
"property1" : "...",
"property2" : "..."
},
"runLogPath" : "...",
"statusPath" : "...",
"inputPath" : "...",
"resultPath" : "...",
"isExecuting" : true,
"executionNode" : "...",
"retryInSafeDebugMode" : true
} ]
GET /runtime/execution
List all of the executions currently in the repository.
Response codes indicate the following:
- 200 OK: The executions list is returned (may be empty)
- 500 Internal Server Error: Unexpected failure within component
Response Body
| media type |
data type |
description |
| application/json |
array of ModelExecution (JSON) |
A JSON array of structures describing the current status of the executions, in order of creation. |
Example
Request
GET /runtime/execution
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
[ {
"id" : "...",
"status" : "OK",
"exitCode" : 12345,
"progress" : 12345.0,
"creation" : 12345,
"start" : 12345,
"finish" : 12345,
"parameters" : {
"property1" : "...",
"property2" : "..."
},
"runLogPath" : "...",
"statusPath" : "...",
"inputPath" : "...",
"resultPath" : "...",
"isExecuting" : true,
"executionNode" : "...",
"retryInSafeDebugMode" : true
} ]
POST /runtime/execution
Schedule a new execution of the model, with the input data & parameters as specified.
Response codes indicate the following:
- 200 OK: The execution has been scheduled
- 400 Bad Request: The execution request is in some way invalid
- 507 Insufficient Storage: The execution could not be scheduled because there isn't enough quota to store the input data; the client should either delete some existing executions or resubmit with a smaller amount of input data.
- 500 Internal Server Error: Unexpected failure within component
Request Body
| media type |
data type |
description |
| application/json |
ExecutionRequestData (JSON) |
A JSON structure describing the input data & parameters for the execution |
Response Body
| media type |
data type |
description |
| application/json |
ModelExecution (JSON) |
A JSON structure describing the current status of the execution. The new execution can be referenced using the unique "execution ID" you obtain from the 'id' field of this. |
Example
Request
POST /runtime/execution
Content-Type: application/json
Accept: application/json
{
"parameters" : {
"property1" : "...",
"property2" : "..."
},
"inputText" : "...",
"inputBase64" : "..."
}
Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"id" : "...",
"status" : "OK",
"exitCode" : 12345,
"progress" : 12345.0,
"creation" : 12345,
"start" : 12345,
"finish" : 12345,
"parameters" : {
"property1" : "...",
"property2" : "..."
},
"runLogPath" : "...",
"statusPath" : "...",
"inputPath" : "...",
"resultPath" : "...",
"isExecuting" : true,
"executionNode" : "...",
"retryInSafeDebugMode" : true
}
POST /runtime/execution
Schedule a new execution of the model, with the input data & parameters as specified by the given form POST. This is usually used for submitting an iframe AJAX request using a form, passing a file from the local file system as input.
Request Body
| media type |
data type |
description |
| multipart/form-data |
(custom) |
A form posting from which the field "input" will be used as the model inputs, and fields with names starting "param-" will be used to set parameters, e.g. in HTML, a field to set the MAX_NUM_EMPLOYEES parameters would be: <input type="text" name="param-MAX_NUM_EMPLOYEES" /> |
Response Body
| media type |
data type |
description |
| text/html;charset=UTF-8 |
object |
An object representing the request response. On success, the returned status code is 200 and the entity is a string containing a JSON ModelExecution structure. On error, the returned status code is something other than 200 and the entity is a string describing the error. |
Example
Request
POST /runtime/execution
Content-Type: multipart/form-data
Accept: text/html;charset=UTF-8
Response
HTTP/1.1 201 Created
Content-Type: text/html;charset=UTF-8
...
GET /runtime/ping
Reads the current server time in milliseconds, useful for checking the component is alive.
Response Body
| media type |
data type |
description |
| application/json |
string (JSON) |
the current server time in milliseconds |
Example
Request
GET /runtime/ping
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
...
GET /runtime/status
Summarize the repository status
Response codes indicate the following:
- 200 OK: The repository status is returned
- 500 Internal Server Error: Unexpected failure within component
Response Body
| media type |
data type |
description |
| application/json |
RepositoryStatus (JSON) |
A JSON document describing the status of the component |
Example
Request
GET /runtime/status
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"componentID" : "...",
"componentEnv" : "...",
"componentVersion" : "...",
"xpressVersion" : "...",
"numGears" : 12345,
"numExecutions" : 12345,
"numExecutionsQueued" : 12345,
"numExecutionsInProgress" : 12345,
"numExecutionsCompleted" : 12345,
"binaryDataSizeMB" : 12345,
"binaryDataQuotaMB" : 12345,
"databaseSizeMB" : 12345
}
GET /runtime/urls
Return the URL of the component instance for each lifecycle
Response Body
| media type |
data type |
description |
| application/json |
map of string (JSON) |
|
Example
Request
GET /runtime/urls
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
...
DELETE /runtime/execution/{id}
Delete an execution. If the execution is not executing, it will be removed from the database and all endpoints associated with the execution ID will subsequently return "404 Not Found". If the execution is currently in progress, it will be flagged as "cancelled" to ensure it is interrupted at the next opportunity, and will be deleted as soon as it either interrupts or completes.
Response codes indicate the following:
- 200 OK: Operation successful
- 404 Not Found: When the execution does not exist in the component
- 500 Internal Server Error: General failure upon trying to delete execution
Request Parameters
| name |
type |
description |
| id |
path |
The execution ID. |
Response Body
| media type |
data type |
description |
| application/json |
object (JSON) |
An OK response if the execution was deleted or flagged for later deletion. |
| application/xml |
anyType (XML) |
Example
Request
DELETE /runtime/execution/{id}
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 204 No Content
Content-Type: application/json
...
GET /runtime/execution/{id}
Return the status of the specified execution.
Response codes indicate the following:
- 200 OK: Operation successful
- 404 Not Found: When the execution does not exist in the component
- 500 Internal Server Error: General failure upon trying to access execution status
Request Parameters
| name |
type |
description |
| id |
path |
The execution ID. |
Response Body
| media type |
data type |
description |
| application/json |
ModelExecution (JSON) |
A JSON structure describing the current status of the execution. |
Example
Request
GET /runtime/execution/{id}
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id" : "...",
"status" : "STOP",
"exitCode" : 12345,
"progress" : 12345.0,
"creation" : 12345,
"start" : 12345,
"finish" : 12345,
"parameters" : {
"property1" : "...",
"property2" : "..."
},
"runLogPath" : "...",
"statusPath" : "...",
"inputPath" : "...",
"resultPath" : "...",
"isExecuting" : true,
"executionNode" : "...",
"retryInSafeDebugMode" : true
}
GET /runtime/execution/{id}/result
Return the result of the executing model, as output by the model itself in a file called 'result'. This is only available after the model execution has completed.
Response codes indicate the following:
- 200 OK: Operation successful
- 404 Not Found: When the execution does not exist, has not completed or the model did not output a result file./li>
- 500 Internal Server Error: General failure upon trying to access the result of the execution
Request Parameters
| name |
type |
description |
| id |
path |
The execution ID. |
Response Body
| media type |
data type |
description |
| application/octet-stream |
object |
The result of the execution |
Example
Request
GET /runtime/execution/{id}/result
Content-Type: */*
Accept: application/octet-stream
...
Response
HTTP/1.1 200 OK
Content-Type: application/octet-stream
...
GET /runtime/execution/{id}/runlog
Return the run log of the specified execution. The run log is the output of the model, including anything the model itself writes to its log, any error messages, and possibly solver diagnostics.
Calling this endpoint before the execution has completed will return the run log output by the model to-date.
Response codes indicate the following:
- 200 OK: Operation successful
- 404 Not Found: When the execution does not exist or the run log can not be found
- 500 Internal Server Error: General failure upon trying to access execution run log
Request Parameters
| name |
type |
description |
| id |
path |
the execution ID |
Response Body
| media type |
data type |
description |
| text/plain;charset=UTF-8 |
object |
The execution run log |
Example
Request
GET /runtime/execution/{id}/runlog
Content-Type: */*
Accept: text/plain;charset=UTF-8
...
Response
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
...
GET /runtime/execution/{id}/runlog
Return part of run log of the specified execution. The run log is the output of the model, including anything the model itself writes to its log, any error messages, and possibly solver diagnostics. The run log fragment will be returned as an array of lines within a JSON structure. The lines do not include trailing newline characters.
The "version" field of the returned structure will only be changed in the case of an execution being restarted. When retrieving something other than the start of the run log, you should always check that this value has not changed since your last call to this endpoint; if it has changed, this means the execution has been restarted and you should retrieve the run log again, starting from line 1.
Response codes indicate the following:
- 200 OK: Operation successful
- 404 Not Found: When the execution does not exist or the run log can not be found
- 500 Internal Server Error: General failure upon trying to access execution run log
Request Parameters
| name |
type |
description |
default |
constraints |
| id |
path |
the execution ID |
|
|
| firstLine |
query |
retrieve a fragment of the run log starting from this line. The run log lines are numbered starting from 1. If unspecified, returns run log starting from line 1. |
1 |
int |
| maxLines |
query |
maximum number of lines to return. If unspecified, will return as many lines as are currently available in the repository. |
2147483647 |
int |
Response Body
| media type |
data type |
description |
| application/json |
RunLogFragment (JSON) |
The execution run log |
Example
Request
GET /runtime/execution/{id}/runlog
Content-Type: */*
Accept: application/json
...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id" : "...",
"version" : "...",
"firstLineNum" : 12345,
"numAvailableLines" : 12345,
"lines" : [ "...", "..." ]
}
© 2001-2023 Fair Isaac Corporation. All rights reserved. This documentation is the
property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not
convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except
solely for internal evaluation purposes to determine whether to purchase a license to the software
described in this documentation, or as otherwise set forth in a written software license agreement
between you and FICO (or a FICO affiliate). Use of this documentation and the software described in
it must conform strictly to the foregoing permitted uses, and no other use is permitted.