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:
| Operation | Method | Path | Purpose |
|---|---|---|---|
| Search the audit trail | POST | /api/v3/audit/search | Retrieve audit records for one or more assets |
| Fetch the next page | GET | /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.
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 class | Description |
|---|---|
UNIVERSAL_CASE | Cases |
MESSAGE_WORKFLOW | Message workflow records |
PROFILE_WORKFLOW | Profile workflow records |
MEDIA_ASSET | Media assets |
OUTBOUND_MESSAGE | Outbound messages |
USER | Users |
SPR_TASK | Tasks |
Asset class and asset IDs must correspond. The IDs you send must belong to the class you name. Start with
UNIVERSAL_CASEwhen validating your integration — it is the value used in the worked examples below.
https://api3.sprinklr.com/{env}/api/v3The 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
prod0returns401 Unauthorizedagainstprod19even when the request is otherwise perfectly formed. When you get an unexpected401, verify the environment before debugging the payload.
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.
| Header | Value | Purpose | Required on |
|---|---|---|---|
Authorization | Bearer {{accessToken}} | Authenticates the user with the server | All requests |
Key | {{apiKey}} | Authenticates the application with the server | All requests |
Content-Type | application/json | Declares the request body media type | POST /audit/search |
Accept | application/json | Declares the acceptable response type | All 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 | Lifetime |
|---|---|
| Authorization code | 10 minutes |
| API key | No expiry |
| Access token | 30 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
AuthorizationorKeyheader values. Every credential on this page is a placeholder.
POST https://api3.sprinklr.com/{env}/api/v3/audit/search| Parameter | Type | Required | Description |
|---|---|---|---|
assetIds | Array of strings | Yes | List of asset IDs whose audit trail you want |
assetClass | String | Yes | The asset class the IDs belong to |
limit | Integer | No | Number of results in the response. Default 50, maximum 200 |
order | String | No | Sorting order — ASC or DESC. Defaults to DESC |
from | Integer | No | Time after which audits are required, in epoch milliseconds |
upto | Integer | No | Time 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
assetIdswithassetId. The request field isassetIds(plural, array). The response field on each record isassetId(singular, string). They are different fields.
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
}'{
"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".
GET /api/v3/audit?id={cursorId}Retrieves the next page of audit records. Use the cursor returned by the previous Audit API response.
| Parameter | In | Type | Description |
|---|---|---|---|
id | query | String | Cursor ID from a previous audit search response |
The parameter is named
id, notcursorId. Always send it — a request with no cursor has no defined result.
curl -X GET \
'https://api3.sprinklr.com/{env}/api/v3/audit?id=638e12816d414169dc5ad755' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Accept: application/json'{
"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.
{
"data": {
"results": [ ... ],
"cursor": "..."
},
"errors": []
}| Field | Type | Description |
|---|---|---|
data.results | Array | Array listing the details of the response |
data.results[].assetClass | String | Asset class for which the request was made |
data.results[].assetId | String | The asset ID from the request |
data.results[].auditDate | Epoch milliseconds | The date on which the change was recorded |
data.results[].userId | Integer | The ID of the user who made the changes |
data.results[].changes | Array | Lists the change details |
data.results[].changes[].fieldName | String | The name of the field that was modified |
data.results[].changes[].oldValues | Array of strings | The old value of the field |
data.results[].changes[].newValues | Array of strings | The new or changed value of the field |
data.cursor | String | Returned when the response has more data than the requested limit. Use it to fetch the next set of data |
errors | Array | Array of error objects. Empty on success |
The auditDate field contains an epoch timestamp in milliseconds.
For example,
| Raw value | UTC |
|---|---|
1650461298712 | 2022-04-20T13:28:18.712Z |
1650461298594 | 2022-04-20T13:28:18.594Z |
1650452106126 | 2022-04-20T10:55:06.126Z |
Parsing
auditDateas 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.
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:
- Send
POST /api/v3/audit/search. - Process the audit records in the response.
- Check whether the response includes a cursor.
- If a cursor is present, send
GET /api/v3/audit?id={cursorId}. - 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 → stopAudit API operations can return the following HTTP status codes:
| HTTP code | Scenario |
|---|---|
200 OK | Success. Audit records returned |
400 Bad Request | Malformed body, missing assetIds or assetClass, invalid assetClass, or a malformed cursor |
401 Unauthorized | Invalid or missing Authorization token or Key header |
403 Forbidden | Caller lacks permission to read the audit trail for that asset |
404 Not Found | The asset or the cursor does not exist |
When the response contains an errors array, each error can include the following fields:
| Field | Type | Description |
|---|---|---|
id | String | Error identifier |
code | Integer | Numeric error code |
message | String | Error 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.
| Symptom | Likely cause | Fix |
|---|---|---|
401 with all headers present | Credentials belong to a different environment | Confirm the key and token were generated for the environment in the base URL |
401 after previously working | Access token expired (30-day default), or a second token was generated for the same API key | Refresh the token; give each service its own key |
401 and only one auth header sent | Both Authorization and Key are required | Send both |
400 citing assetIds | Sent assetId (singular) instead of assetIds | Use assetIds, and send it as an array |
Client-side type error on assetIds | Sent integers where strings are expected | Quote the IDs: ["10520954"] |
400 on assetClass | The asset class does not match the IDs sent | Confirm the IDs belong to the class you named |
404 on the cursor call | Cursor expired, already consumed, or copied from a different search | Re-run the search from the beginning; do not persist cursors |
| Pagination never terminates | Your loop checks for only one terminal form | Treat absent, null, and "" as terminal; add a max-iteration guard |
| Dates decode to 1970 | auditDate is epoch milliseconds, parsed as seconds | Parse as milliseconds |
| Duplicate-looking records | Multiple audit records can share one user action, milliseconds apart | Do not use auditDate as a unique key |
| More records than expected | limit defaults to 50 | Set limit explicitly on every call |
| V2 | V3 |
|---|---|
POST /api/v2/audit/fetch | POST /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}| V2 | V3 | Change |
|---|---|---|
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.
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.
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.
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.
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.
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.
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 → stopSend the cursor you last received, not one from a previous run. Guard the loop with a maximum iteration count.
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.
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
limitexplicitly. Maximum is200; default is50. orderacceptsASCandDESCand defaults toDESC.
Asset classes
- Asset class and asset IDs must correspond — the IDs must belong to the class you name.
Time windows
fromanduptoare epoch milliseconds, matchingauditDate.- 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
auditDateis epoch milliseconds. Parsing as seconds yields 1970.- Records can be milliseconds apart.
auditDateis 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
403is a permission gap, not a malformed request.