API Reference
This page shows how to use the Xtract Universal.iQ REST API.
Xtract Universal.iQ offers a REST API for listing configured services, querying service metadata, and executing services.
Base URL
The base URL uses the following format: [protocol]://[host or IP address]:[port].
| Protocol | Format | Example |
|---|---|---|
| HTTP | http://[host]:[port] | http://localhost:8080 |
| HTTPS | https://[host]:[port] | https://example.com:8080 |
The default port for both HTTP and HTTPS is 8080. For HTTPS, the server certificate provides the host name.
Endpoint Overview
All paths below are relative to the base URL:
Note
The {serviceName} path parameter identifies existing Xtract Universal.iQ services. For services in folders, combine the folder name and service name with commas, e.g., the service KNA1 in the folder S4HANA is addressed as S4HANA,KNA1. The URL-encoded form S4HANA%2CKNA1 represents the same name.
HTTP Status Codes
Error responses use text/plain. The following table summarizes the status codes of the API:
| Status | Meaning |
|---|---|
200 | Request handled. When running services, this does not guarantee a successful data extraction. |
400 | Invalid request, e.g., an invalid service name or request data. |
401 | Authentication is required or the supplied credentials are invalid. |
403 | The caller lacks the required server or service access. |
404 | The requested service does not exist. |
500 | The server could not complete the request. |
Run Services
Synchronous Execution
Starts a service run and waits for it to finish before returning a response. The response depends on the destination:
- Pull destinations return data to the caller in the HTTP response. Examples include the HTTP and Microsoft Power BI destinations. The response contains JSON or CSV data, depending on the destination configuration.
- Push destinations write SAP data to a target system, e.g., databases or storages. Examples include Microsoft SQL Server and Microsoft Azure Storage. The HTTP response contains run statistics, not the SAP records. The data is available in the target system.
Asynchronous Execution
Starts a service run and depending on the destination, returns a response immediately without waiting for the run to finish.
- Pull destinations return data to the caller in the HTTP response.
/startwaits for the data to become available, then returns it as JSON or CSV instead of run statistics. - Push destinations write SAP data to a target system, e.g., databases or storages.
/startreturns a response immediately without waiting for the run to finish. The response contains the run statistics available at that time.
Runtime Parameters
The supported runtime parameter names and accepted values depend on the service configuration.
- For
GET, supply runtime parameters in the service URL, see Pass Query Parameters. - For
POST, supply an optional JSON object that contains the runtime parameter names and values, see Pass Body Parameters. SetContent-Type: application/json.
For more information, see Parameter Overview or retrieve the parameter definitions of a service using Get Service Details.
Example Requests
The following requests use the service S4HANA,KNA1 to extract customer master data from an SAP table. The service supports the runtime parameters rows and whereClause. The examples omit authentication headers. Include them when required.
Responses
The destination determines whether the response contains run statistics or SAP records:
- Pull destinations return data to the caller in the HTTP response. Examples include the HTTP destination and the Microsoft Power BI connector. The response contains JSON or CSV data, depending on the destination configuration.
- Push destinations write SAP data to a target system, e.g., database or storage locations. Examples include Microsoft SQL Server and Microsoft Azure Storage. The HTTP response contains run statistics, not the SAP records. The data is available in the target system.
Warning
Service finishes with errors despite HTTP 200 response
HTTP 200 means that the request was handled; it does not indicate that the extraction completed successfully.
The run-statistics can contain the following fields:
| Field | Type, when available | Description |
|---|---|---|
duration | String | Execution duration in ISO 8601 format. |
rowsCount | Integer | Number of processed rows. |
state | String | Current or final run state, e.g., FinishedNoErrors. |
processId | Integer | Worker process identifier. |
webLogTimestamp | String | Associated web-log timestamp. |
extraction | String | Service name associated with the run. |
destination | String | Destination connection name. |
source | String | Source connection name. |
sapStatistics | Object | SAP-specific statistics, when supplied by the source connector. |
licenseNumber | String | License number associated with the run. |
error | String | Error information reported by the run. |
{
"duration": "PT00H00M02.328S",
"rowsCount": 2726,
"state": "FinishedNoErrors",
"webLogTimestamp": "2026-11-03_13:00:26.628",
"extraction": [
"S4HANA",
"KNA1"
],
"destination": [
"azure_storage"
],
"source": [
"s4h"
],
"sapStatistics": {
"Version": 758,
"DeploymentModel": "OnPrem",
"SystemId": "10925025821593471230",
"ApplicationServer": "7962283119924088786",
"ProductName": "S4HANA ON PREMISE"
}
}
Get List of Services
Returns a list of all services the caller has access to. Services that cannot be read are omitted from the list.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
destination | No | Filters services by connection type, e.g., MicrosoftFabricOneLake, Iceberg, AmazonS3, etc. |
Response
| Field | Description |
|---|---|
name | Service name as a comma-separated path. |
type | Service type, e.g, Table, CDSFlow, etc. |
source | Source connection object with name and type (SapRfc or SapOdata). |
destination | Destination connection object with name and type. |
created | Creation information with timestamp and, when available, user. |
lastChange | Last-change information with timestamp and, when available, user. |
sapObject | Technical name of the extracted SAP object. |
latestRun | Latest-run summary with duration and state. |
Example
{
"services": [
{
"name": "S4HANA,KNA1",
"type": "Table",
"source": {
"name": "s4h",
"type": "SapRfc"
},
"destination": {
"name": "s3",
"type": "AmazonS3"
},
"created": {
"user": "alice",
"timestamp": "20261102T110438.462Z"
},
"lastChange": {
"user": "bob",
"timestamp": "20261103T133035.775Z"
},
"sapObject": "KNA1",
"latestRun": {
"duration": "PT00H00M00.031S",
"state": "FinishedNoErrors"
}
}
]
}
Get Service Details
Returns the metadata of a service, including result columns and runtime parameter definitions.
Response
| Field | Subfield | Description |
|---|---|---|
name | Name of the service, including the parent folder. | |
columns | Metadata of result columns. | |
name | Column name. | |
description | Column description, omitted when empty. | |
type | Runtime result representation, e.g., StringLengthMax, Decimal, or Date. | |
length | Column length. | |
isPrimaryKey | Indicates if the column is part of the primary key. | |
decimalsCount | Decimal places, included only for Decimal columns. | |
referenceField | Referenced SAP field, omitted when empty. | |
referenceTable | Referenced SAP table, omitted when empty. | |
parameters | Runtime parameter definitions contains two groups of parameters: • service contains standard runtime parameters for the service type, e.g., whereClause for Table services. • custom contains custom runtime parameters configured for the service. If no custom runtime parameters are defined, the custom group is omitted. | |
name | Name of the runtime parameter that can be used in execution requests. | |
description | Description of the parameter. | |
type | Data type of the parameter, e.g., Text or Number. | |
default | Optional default value. |
Example
{
"name": [
"S4HANA",
"MARA"
],
"columns": [
{
"name": "MATNR",
"description": "Material Number",
"type": "StringLengthMax",
"length": 40,
"isPrimaryKey": true
},
{
"name": "ERSDA",
"description": "Created On",
"type": "Date",
"isPrimaryKey": false
},
{
"name": "NTGEW",
"description": "Net Weight",
"type": "Decimal",
"length": 13,
"decimalsCount": 3,
"isPrimaryKey": false,
"referenceField": "GEWEI",
"referenceTable": "MARA"
}
],
"parameters": {
"service": [
{
"name": "packageSize",
"description": "Rows per package",
"type": "Number",
"default": 50000
},
{
"name": "rows",
"description": "Total rows limit",
"type": "Number",
"default": 0
},
{
"name": "whereClause",
"description": "ABAP SQL WHERE clause",
"type": "Text",
"default": ""
}
],
"custom": [
{
"name": "myParameter",
"description": "",
"type": "Text",
"default": null
}
]
}
}
Get Service API Descriptions
Generates a Swagger 2.0 description for the requested service.
Generates an OpenAPI 3.2 description for the requested service.

