Skip to content

Audit API V3

The Audit API retrieves the change history for Sprinklr assets. Developers can use the API to identify what changed, when the change occurred, and the user associated with the change. The corresponding change history is available in the Activity tab in Sprinklr.

Audit API V3 provides the following operations:

OperationMethodPathPurpose
Search the audit trailPOST/api/v3/audit/searchRetrieve audit records for one or more assets
Fetch the next pageGET/api/v3/audit?id={cursorId}Retrieve the next page of audit records

Start with POST /api/v3/audit/search. If the response includes a cursor, pass it to GET /api/v3/audit to retrieve the next page.

Asset classes

An asset class is the kind of object being audited — features present on Sprinklr's platform, such as Account, Outbound Message, Case, or Profile.

Every request pairs an asset class with one or more asset IDs belonging to that class. The API then returns the change history for those assets.

Asset classDescription
UNIVERSAL_CASECases
MESSAGE_WORKFLOWMessage workflow records
PROFILE_WORKFLOWProfile workflow records
MEDIA_ASSETMedia assets
OUTBOUND_MESSAGEOutbound messages
USERUsers
SPR_TASKTasks

Asset class and asset IDs must correspond. The IDs you send must belong to the class you name. Start with UNIVERSAL_CASE when validating your integration — it is the value used in the worked examples below.


Base URL

https://api3.sprinklr.com/{env}/api/v3

The Audit API endpoints are:

https://api3.sprinklr.com/{env}/api/v3/audit/search
https://api3.sprinklr.com/{env}/api/v3/audit?id={cursorId}

Replace {env} with your assigned Sprinklr environment. For the production environment at app.sprinklr.com, omit the {env} segment from the URL. For information about supported environments and how to identify your environment, see APIs | Sprinklr Developer Portal.

Environment-scoped credentials. API keys and access tokens are scoped to a single environment. A key generated for prod0 returns 401 Unauthorized against prod19 even when the request is otherwise perfectly formed. When you get an unexpected 401, verify the environment before debugging the payload.


Authentication

Audit API V3 uses OAuth 2.0 bearer authentication and an API key. Include both the access token and API key with every request.

See API Overview for portal registration, API key and secret generation, and the Authorize flow.

Required headers

HeaderValuePurposeRequired on
AuthorizationBearer {{accessToken}}Authenticates the user with the serverAll requests
Key{{apiKey}}Authenticates the application with the serverAll requests
Content-Typeapplication/jsonDeclares the request body media typePOST /audit/search
Acceptapplication/jsonDeclares the acceptable response typeAll requests

Both Authorization and Key are required on every call. Sending only one returns 401.

Content-Type is only meaningful on the POST, since the GET has no body.

Credential lifetimes

CredentialLifetime
Authorization code10 minutes
API keyNo expiry
Access token30 days by default

One token pair per API key. Generating a new access token for an API key invalidates the previously issued token and refresh token for that key. If two services share one key and both refresh, they will knock each other offline. Give each service its own key.

Credential hygiene. Never commit an access token or API key to source control, never paste one into a ticket or chat, and never log the Authorization or Key header values. Every credential on this page is a placeholder.


Search the audit trail

POST https://api3.sprinklr.com/{env}/api/v3/audit/search

Request body parameters

ParameterTypeRequiredDescription
assetIdsArray of stringsYesList of asset IDs whose audit trail you want
assetClassStringYesThe asset class the IDs belong to
limitIntegerNoNumber of results in the response. Default 50, maximum 200
orderStringNoSorting order — ASC or DESC. Defaults to DESC
fromIntegerNoTime after which audits are required, in epoch milliseconds
uptoIntegerNoTime before which audits are required, in epoch milliseconds

Send asset IDs as an array of strings:

"assetIds": [ "10520954" ]

Batch multiple IDs into a single call rather than looping one asset at a time.

Use from and upto to limit the search to a specific time range. Both values use epoch milliseconds, consistent with the auditDate value in the response.

Do not confuse assetIds with assetId. The request field is assetIds (plural, array). The response field on each record is assetId (singular, string). They are different fields.

Example request

curl -X POST \
  'https://api3.sprinklr.com/{env}/api/v3/audit/search' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "assetIds": [
      "10520954"
    ],
    "assetClass": "UNIVERSAL_CASE",
    "order": "DESC",
    "limit": 2
  }'

Example response

{
  "data": {
    "results": [
      {
        "assetClass": "UNIVERSAL_CASE",
        "assetId": "10520954",
        "auditDate": 1650461298712,
        "userId": 0,
        "changes": [
          {
            "fieldName": "Messages",
            "oldValues": [],
            "newValues": [
              "New value 1"
            ]
          }
        ]
      },
      {
        "assetClass": "UNIVERSAL_CASE",
        "assetId": "10520954",
        "auditDate": 1650461298594,
        "userId": 0,
        "changes": [
          {
            "fieldName": "Message Sentiment",
            "oldValues": [],
            "newValues": [
              "New value 2"
            ]
          }
        ]
      }
    ],
    "cursor": "638e12816d414169dc5ad755"
  },
  "errors": []
}

In this example, the response contains a cursor because additional audit records are available. limit was 2 and a cursor came back, so more data is available.

Note the ordering: 1650461298712 precedes 1650461298594, which is descending by auditDate — consistent with the requested "order": "DESC".


Fetch the next page by cursor

GET /api/v3/audit?id={cursorId}

Retrieves the next page of audit records. Use the cursor returned by the previous Audit API response.

Query parameters

ParameterInTypeDescription
idqueryStringCursor ID from a previous audit search response

The parameter is named id, not cursorId. Always send it — a request with no cursor has no defined result.

Example request

curl -X GET \
  'https://api3.sprinklr.com/{env}/api/v3/audit?id=638e12816d414169dc5ad755' \
  -H 'Authorization: Bearer {{accessToken}}' \
  -H 'Key: {{apiKey}}' \
  -H 'Accept: application/json'

Example response

{
  "data": {
    "results": [
      {
        "assetClass": "UNIVERSAL_CASE",
        "assetId": "10520954",
        "auditDate": 1650452106126,
        "userId": 0,
        "changes": [
          {
            "fieldName": "Messages",
            "oldValues": [],
            "newValues": [
              "Test1"
            ]
          }
        ]
      }
    ],
    "cursor": "627e334a25033713a3cb8887"
  },
  "errors": []
}

The response shape is identical to the search response, including its own cursor for the page after this one.

If the response includes another cursor, use it to request the following page. Continue until the response no longer provides a cursor.


Response fields

{
  "data": {
    "results": [ ... ],
    "cursor": "..."
  },
  "errors": []
}
FieldTypeDescription
data.resultsArrayArray listing the details of the response
data.results[].assetClassStringAsset class for which the request was made
data.results[].assetIdStringThe asset ID from the request
data.results[].auditDateEpoch millisecondsThe date on which the change was recorded
data.results[].userIdIntegerThe ID of the user who made the changes
data.results[].changesArrayLists the change details
data.results[].changes[].fieldNameStringThe name of the field that was modified
data.results[].changes[].oldValuesArray of stringsThe old value of the field
data.results[].changes[].newValuesArray of stringsThe new or changed value of the field
data.cursorStringReturned when the response has more data than the requested limit. Use it to fetch the next set of data
errorsArrayArray of error objects. Empty on success

Intepret auditDate

The auditDate field contains an epoch timestamp in milliseconds.

For example,

Raw valueUTC
16504612987122022-04-20T13:28:18.712Z
16504612985942022-04-20T13:28:18.594Z
16504521061262022-04-20T10:55:06.126Z

Parsing auditDate as seconds yields a date in 1970. This is the most common integration error against this API.

Multiple audit records can have timestamps only a few milliseconds apart. Do not assume that auditDate uniquely identifies an audit record. Consecutive records can be milliseconds apart — the two values above differ by 118 ms. A single user action can produce several audit records, so do not assume one record per user interaction, and do not use auditDate as a unique key.

Intepret changes

changes is an array — one entry per field modified in that audit event. Each entry has fieldName, oldValues, and newValues. Both value fields are arrays, because a field can hold multiple values.

Each entry includes fieldName: Name of the modified field oldValues: Values before the change newValues: Values after the change

Both oldValues and newValues are arrays because a field can contain multiple values.

Audit API V3 uses cursor-based pagination.

Use the following sequence:

  1. Send POST /api/v3/audit/search.
  2. Process the audit records in the response.
  3. Check whether the response includes a cursor.
  4. If a cursor is present, send GET /api/v3/audit?id={cursorId}.
  5. Repeat until the response no longer includes a cursor.

Example

POST /api/v3/audit/search   { "assetIds": ["10520954"], "assetClass": "UNIVERSAL_CASE", "limit": 200 }
  → results and cursor "638e12816d414169dc5ad755"

GET  /api/v3/audit?id=638e12816d414169dc5ad755
  → results and cursor "627e334a25033713a3cb8887"

GET  /api/v3/audit?id=627e334a25033713a3cb8887
  → results without another cursor, cursor absent/null/empty  → stop

Error Responses

Audit API operations can return the following HTTP status codes:

HTTP codeScenario
200 OKSuccess. Audit records returned
400 Bad RequestMalformed body, missing assetIds or assetClass, invalid assetClass, or a malformed cursor
401 UnauthorizedInvalid or missing Authorization token or Key header
403 ForbiddenCaller lacks permission to read the audit trail for that asset
404 Not FoundThe asset or the cursor does not exist

When the response contains an errors array, each error can include the following fields:

FieldTypeDescription
idStringError identifier
codeIntegerNumeric error code
messageStringError message key, for example account.not.found

Error responses return data as null.

Example

{
  "data": null,
  "errors": [
    {
      "id": "error-id",
      "code": 400,
      "message": "account.not.found"
    }
  ]
}

Inspect both the HTTP status and the errors array when handling unsuccessful requests.


Troubleshooting

SymptomLikely causeFix
401 with all headers presentCredentials belong to a different environmentConfirm the key and token were generated for the environment in the base URL
401 after previously workingAccess token expired (30-day default), or a second token was generated for the same API keyRefresh the token; give each service its own key
401 and only one auth header sentBoth Authorization and Key are requiredSend both
400 citing assetIdsSent assetId (singular) instead of assetIdsUse assetIds, and send it as an array
Client-side type error on assetIdsSent integers where strings are expectedQuote the IDs: ["10520954"]
400 on assetClassThe asset class does not match the IDs sentConfirm the IDs belong to the class you named
404 on the cursor callCursor expired, already consumed, or copied from a different searchRe-run the search from the beginning; do not persist cursors
Pagination never terminatesYour loop checks for only one terminal formTreat absent, null, and "" as terminal; add a max-iteration guard
Dates decode to 1970auditDate is epoch milliseconds, parsed as secondsParse as milliseconds
Duplicate-looking recordsMultiple audit records can share one user action, milliseconds apartDo not use auditDate as a unique key
More records than expectedlimit defaults to 50Set limit explicitly on every call

Migrating from V2

Endpoint mapping

V2V3
POST /api/v2/audit/fetchPOST /api/v3/audit/search
GET /api/v2/audit?id={cursorId}GET /api/v3/audit?id={cursorId}
- POST https://api3.sprinklr.com/{env}/api/v2/audit/fetch
+ POST https://api3.sprinklr.com/{env}/api/v3/audit/search

- GET  https://api3.sprinklr.com/{env}/api/v2/audit?id={cursorId}
+ GET  https://api3.sprinklr.com/{env}/api/v3/audit?id={cursorId}

Field mapping

V2V3Change
assetIds (body)assetIds (body)None
assetClass (body)assetClass (body)None
order (body)order (body)None
limit (body)limit (body)None
—from (body)New in V3 — lower time bound
—upto (body)New in V3 — upper time bound
id (query, cursor)id (query, cursor)None

The request and response contracts are otherwise unchanged. Apart from the path and the two new optional time-window fields, a working V2 integration becomes a working V3 integration by changing v2 to v3 and fetch to search.

Common Use Cases

Find who changed a case and when

A case was resolved incorrectly and you need the change history.

{
  "assetIds": ["10520954"],
  "assetClass": "UNIVERSAL_CASE",
  "order": "DESC",
  "limit": 50
}

DESC puts the most recent change first, which is usually what you want when investigating a recent incident.

Export a full history for a compliance archive

Send up to the maximum limit of 200, then follow cursor until the result set is exhausted. Use ASC so the archive reads chronologically:

{
  "assetIds": ["10520954", "10520955", "10520956"],
  "assetClass": "UNIVERSAL_CASE",
  "order": "ASC",
  "limit": 200
}

assetIds accepts multiple IDs in one call — batch them rather than looping one asset at a time.

Run an incremental nightly sync

You mirror the audit trail into a data warehouse and only want what is new. Store the previous run's high-water mark and pass it as from:

{
  "assetIds": ["10520954"],
  "assetClass": "UNIVERSAL_CASE",
  "from": 1650452106126,
  "upto": 1650461298712,
  "order": "ASC",
  "limit": 200
}

This is materially cheaper than pulling the full history and filtering client-side. Prefer a slightly overlapping window with de-duplication so that records written exactly on a boundary are never missed.

Detect changes to a specific field

There is no server-side field filter. Fetch the audit trail for the asset and filter changes[].fieldName client-side. Narrow the volume first with from and upto rather than filtering a full history.

Reconstruct an asset's state at a point in time

Fetch with ASC order and upto set to your target timestamp, then replay changes[].newValues forward. Because oldValues is also returned, you can equally walk backward from the current state.

Page through a large result set

POST /api/v3/audit/search   { "assetIds": ["10520954"], "assetClass": "UNIVERSAL_CASE", "limit": 200 }
  → results[…200], cursor "638e12816d414169dc5ad755"

GET  /api/v3/audit?id=638e12816d414169dc5ad755
  → results[…200], cursor "627e334a25033713a3cb8887"

GET  /api/v3/audit?id=627e334a25033713a3cb8887
  → results[…], cursor absent/null/empty  → stop

Send the cursor you last received, not one from a previous run. Guard the loop with a maximum iteration count.

Feed a governance dashboard

The same information is available in the platform under the Activity tab. Use this API when you need that data outside Sprinklr — in a SIEM, a compliance warehouse, or an internal audit tool. If your users are already working in Sprinklr, the Activity tab needs no integration at all.


Best practices

Request fields

  • The request field is assetIds — plural, and an array.
  • Quote asset IDs as strings.
  • Batch multiple IDs into one call rather than looping.
  • Always set limit explicitly. Maximum is 200; default is 50.
  • order accepts ASC and DESC and defaults to DESC.

Asset classes

  • Asset class and asset IDs must correspond — the IDs must belong to the class you name.

Time windows

  • from and upto are epoch milliseconds, matching auditDate.
  • Use an overlapping window with de-duplication for incremental ingestion.

Cursors

  • Treat the cursor as opaque. Do not parse, construct, or increment it.
  • Cursors are single-use and query-scoped. Never mix a cursor from one search into another.
  • Do not persist cursors across runs; restart the search instead.
  • Handle absent, null, and empty-string cursors as terminal, and add a max-iteration guard.

Timestamps

  • auditDate is epoch milliseconds. Parsing as seconds yields 1970.
  • Records can be milliseconds apart. auditDate is not a unique key.

Rate limiting

  • Cursor loops are the most likely trigger for rate limiting. Add backoff and avoid tight paging loops.

Permissions

  • Audit data is governance data. A 403 is a permission gap, not a malformed request.