list_sync_jobs

Nl2sqlApi.list_sync_jobs(role_id, tenant=None, offset=None, limit=None, sortorder=None, sortby=None, projection_expression=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

List SQL AI documents sync jobs

Returns a paginated history of the jobs that sync SQL AI training documents into the chatbot’s knowledge base. Requires SQLAI to be present in the environment’s enabled AI services; otherwise the request fails with AI-1004. Pagination: read next_available in the response. While it is “yes”, request the next page by advancing offset by limit. When it is “no” this was the last page and the client must stop. Note that supplying projectionExpression changes the response into a bare array and drops the pagination keys entirely, so do not combine it with paging.

Parameters:

• role_id (str) – Amorphic role ID the request is authorized against. The role must carry the playground.view permission. (required)

• tenant (str) – Tenant whose sync-job history to return. Defaults to the environment’s own tenant. The value is not validated and no access check is applied to it: an unknown tenant simply yields an empty list rather than an error.

• offset (int) – One-based index of the first record to return.

• limit (int) – Maximum number of sync jobs to return in one page. Values above 1000 are rejected with GE-1028. Note that this differs from the training-documents listing, which reports the same condition as IPV-1050.

• sortorder (str) – Direction to sort by. Only the exact value “desc” sorts descending; the backend treats every other value as ascending rather than rejecting it.

• sortby (str) – Attribute to sort by. The backend does not validate this value: naming an attribute that is absent from any record, such as EndTime on a still-running job, causes the request to fail with HTTP 500. Prefer an attribute that is always present.

• projection_expression (str) – Comma-separated list of attributes to return per sync job. Caveat: supplying this parameter changes the response body from the paginated object into a bare JSON array of sync-job objects, discarding next_available, count and total_count. Omit it if the client relies on pagination.

• _request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.

• _request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.

• _content_type (str, Optional) – force content-type for the request.

• _headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.

• _host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

NL2SQLDocumentsSyncJobs

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /nl2sql/sync-jobs

Parameter examples

Name	In	Example
role_id	header	"role-admin"
tenant	query	"amorphic"
offset	query	1
limit	query	100
sortorder	query	"desc"
sortby	query	"LastModifiedTime"
projectionExpression	query	"RunId,RunStatus,StartTime"

Success (HTTP 200)

Page of sync jobs. Check next_available to decide whether to request a further page. When projectionExpression is supplied the body is a bare array instead, with no pagination keys.

One finished run and one still in progress

{
  "SyncJobs": [
    {
      "RunId": "AB12CD34EF",
      "RunStatus": "COMPLETE",
      "TenantName": "amorphic",
      "StartTime": "2025-01-15 10:30:00",
      "EndTime": "2025-01-15 10:38:12",
      "TriggeredBy": "user1",
      "Message": "Sync completed successfully",
      "RunStatistics": {
        "DocumentsScanned": 120,
        "NewDocumentsIndexed": 8,
        "ModifiedDocumentsIndexed": 3,
        "DocumentsDeleted": 1,
        "DocumentsFailed": 0
      },
      "LastModifiedTime": "2025-01-15 10:38:12",
      "LastModifiedBy": "user1"
    },
    {
      "RunId": "GH56IJ78KL",
      "RunStatus": "IN_PROGRESS",
      "TenantName": "amorphic",
      "StartTime": "2025-01-16 09:00:00",
      "TriggeredBy": "user1",
      "Message": "Sync in progress",
      "LastModifiedTime": "2025-01-16 09:00:00",
      "LastModifiedBy": "user1"
    }
  ],
  "next_available": "no",
  "count": 2,
  "total_count": 2
}

No sync jobs have been run for this tenant

{
  "SyncJobs": [],
  "next_available": "no",
  "count": 0,
  "total_count": 0
}

Errors

Documented error codes: AI-1004, GE-1028, AUTH-1001, AUTH-1030.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: AI-1004 (SQLAI is not enabled), GE-1028 (limit above 1000), AUTH-1001 (role_id header missing), AUTH-1030 (role lacks playground.view).

limit above the maximum of 1000

{
  "Message": "GE-1028 - Out of range for items per page, Limit is 1000"
}

SQLAI is not enabled for this environment

{
  "Message": "AI-1004 - SQLAI is not enabled. Please contact the administrator to enable it."
}

HTTP 500

Something went wrong at backend