Initializing help system before first use

RuntimeEndpoints

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" : "OK",
  "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" : "LOAD_ERROR",
  "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" : "ERROR",
  "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" : "FDCLOSED",
  "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}/input

Return the input file of the specified execution, as given to the 'execution' endpoint when originally scheduling the job, and passed to the Model itself in a file called 'input'.

Response codes indicate the following:
  • 200 OK: Operation successful
  • 404 Not Found: When the execution does not exist or was created without specified input data.
  • 500 Internal Server Error: General failure upon trying to access the input 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 input of the execution

Example

Request
GET /runtime/execution/{id}/input
Content-Type: */*
Accept: application/octet-stream

                
...
                
              
Response
HTTP/1.1 200 OK
Content-Type: application/octet-stream

                
...
                
              

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-2024 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.