Get audit records

The audit retrieval endpoint allows administrators to access detailed audit records for their tenant. Use this endpoint to track and analyze operational activities such as user logins, device usage, configuration changes, and role assignments.

You can filter audit events by status, resource type, resource ID, action, actor type, and time range to focus on specific events.

The response includes comprehensive details for each event, including the actor, affected resource, action performed, timestamps, and a human-readable description. All filter parameters are optional and can be combined as needed to refine your search. The retrieved audit records reflect data from one hour prior to your call.

Only users with the Administrator role can use this API endpoint.

On this page:

Prerequisites

This endpoint requires a user with Administrator role.

Limitations

This endpoint is available upon request. To have it enabled in your cloud, contact Perfecto Support.

Endpoint URL

URL	Copy `https://<your_cloud>.app.perfectomobile.com/api/v1/audit/search`
Method	`POST`

Header parameters

Name	Description	Notes
Perfecto-Authorization	Security Token	Only an Administrator user can access this url

Request body

Parameter	Type	Description	Sample values
`status`	string	Outcome of the action	Success Failure
`resourceType`	string	What is affected: `user`, `config`, `policy`, `dataset`, `report`	`device` `execution` `artifact` `directory` `config` `Script` `Repository` `user`
`resourceId`	string	Name of the user who has performed the operation device ID Test Execution ID Uploaded/edited/moved/deleted artifact Name Added/deleted/moved directory name Feature setting name Created/updated/deleted device group name Saved/updated script name Created/updated/deleted user name Created/updated/deleted user group name	User: `bob.smith` Device ID: `A24AFDF38A8A3BC2E275B16199093AE61071DD5A` Test execution ID: `c943f67e-de15-4514-a254-8860a0c628b5` Artifact name: `test.ipa` Directory name: `testDir/subTestDir` Feature setting name: `test_1_FS53` Script name: `PRIVATE:Demo21.xml` User name: `z-automation-Audit_User22` Group name: `Testing_test27_91480`
`action`	string	Verb describing what happened: `create`, `update`, `delete`, `login`, `config_update`, `grant_permission`	`Update Feature setting` `Open device` `Close device` `Test Execution` `Upload artifact` `Edit artifact` `Move artifact` `Delete artifact` `Add directory` `Delete directory` `Rename directory` `Move directory` `Insert feature setting` `Update feature setting` `Insert system setting` `Update system setting` `Delete feature setting` `Create device group` `Update device group` `Delete device group` `Add devices to group` `Remove devices from group` `Release device` `Delete device` `Connect device` `Disconnect device` `Update device` `Save or update script` `Delete Repository` `Create Repository` `Create User` `Delete User` `Update User` `Create User group` `Delete User group` `Update User group` `Add user role` `LOGIN` `LOGOUT` `LOGIN_ERROR` `GENERATE_SECURITY_TOKEN` `USE_SECURITY_TOKEN` `USE_SECURITY_TOKEN_ERROR`
`description`	string	Human-readable summary of the action	`Updating a feature setting` `Opening a device` `Closing a device` `Executing a test` `Uploading a artifact` `Editing a artifact` `Moving a artifact` `Deleting a artifact` `Adding a directory` `Deleting a directory` `Renaming a directory` `Moving a directory` `Inserting a new feature setting` `Updating a feature setting` `Inserting a new system setting` `Updating a system setting` `Deleting a feature setting` `Creating a new device group` `Updating a device group details` `Deleting a device group` `Adding new devices to group` `Removing a devices from group` `Releasing a device` `Deleting a device` `Connecting a device` `Disconnecting a device` `Updating a device` `Saving or updating a script` `Deleting a Repository` `Creating a new Repository` `Creating a new user` `Deleting a user` `Updating a user details` `Creating a new user group` `Deleting a user group` `Updating a user group details` `Adding a new user role` `User logged in` `User login failed` `User logged out` `User generated security token` `User failed to use security token`
`actorType`	string	`user`, `admin`, etc.	`user` `admin`
`traceId`	string	Link to system log trace (Unique value)	`2cb2986430cf420f97ce0a74e69ffd0f`
`actorId`	string	The user or system that performed the action (Email ID of that user)	`bob.smith@example.com`
`timestampFrom`	string	Starting TimeStamp for getting a Logs	`2025-12-15T00:00:000Z`
`timestampTo`	string	End TimeStamp for getting a Logs	`2025-12-16T00:00:000Z`
`size`	integer	How many audit records to retrieve. By default, 1000 records are retrieved.	`1000`
`from`	integer	Page number	`2`

Examples

To fetch audit logs based on status:

Copy

JSON request

{
    "status": "SUCCESS"
}

To fetch audit logs based on resource:

Copy

JSON request

{
    "resource_type": "user"
}

To fetch audit logs based on resourceId:

Copy

JSON request

{
    "resourceId": "z-automation-Audit_User23"
}

To fetch audit logs based on filter action:

Copy

JSON request

{
    "action": "Update User"
}

To fetch audit logs based on filter description:

Copy

JSON request

{
    "description": "Updating a user details"
}

To fetch audit logs based on filter actorType:

Copy

JSON request

{
    "actorType": "user"
}

To fetch audit logs based on filter traceId:

Copy

JSON request

{
    "traceId": "fa10c3efcd3342b9872471a2891ecf30"
}

To fetch audit logs based on filter actorId:

Copy

JSON request

{
    "actorId": "bob.smith@example.com"
}

To fetch audit logs based on filter timestampFrom:

Copy

JSON request

{
    "timestampFrom": "2025-12-17T00:00:00.000Z"
}

To fetch audit logs based on filter timestampTo:

Copy

JSON request

{
    "timestampTo": "2025-12-17T00:00:00.000Z"
}

To fetch audit logs based on filter size:

Copy

JSON request

{
    "size": 500
}

To fetch audit logs based on filter from:

Copy

JSON request

{
    "from": 3
}

Passing all parameters in a request:

Copy

JSON request

{
    "status": "SUCCESS",
    "resourceType": "user", 
    "resourceId": "z-automation-Audit_User23", 
    "action": "Update User", 
    "description": "Updating a user details",
    "actorType": "user",
    "traceId": "fa10c3efcd3342b9872471a2891ecf30",
    "actorId": "bob.smith@example.com",
    "timestampFrom": "2025-12-17T00:00:00.000Z",
    "timestampTo": "2025-12-17T00:00:00.000Z",
    "size": 500,
    "from": 3
}

Success response

Code 200 OK

Copy

JSON response

{
    "took": 5,
    "timed_out": false,
    "_shards": {
        "total": 4,
        "successful": 4,
        "skipped": 2,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 166,
            "relation": "eq"
        },
        "max_score": null,
        "hits": [
            {
                "_index": "perfecto-000058",
                "_id": "FeQU6ZoB-PNmllGN05rh",
                "_score": null,
                "_source": {
                    "status": "SUCCESS",
                    "service": "feature-settings-service",
                    "timestamp": "2025-12-04T11:17:24.983Z",
                    "resourceId": "user-plans.license.gold.virtualDevice",
                    "actorType": "user",
                    "@timestamp": "2025-12-04T11:17:27.000Z",
                    "@version": "1",
                    "region": "01",
                    "description": "Publish a new feature setting",
                    "action": "Publish feature setting",
                    "actorId": "offline_job",
                    "resourceType": "config",
                    "tags": [
                        "tail.0"
                    ],
                    "trace_id": "bf686bab4d924859801155dccb936680",
                    "custom_fields": {
                        "value": "true",
                        "tenantId": "[demo, <your-tenant>]",
                        "name": "user-plans.license.gold.virtualDevice"
                    },
                    "hostname": "7f78f374eedc",
                    "tenant_id": "operator",
                    "module": "feature-settings",
                    "changes": {
                        "description": {
                            "old": "Control code generation feature for a particular tenant independently of the license",
                            "new": "Enable the code generation feature for AI commands"
                        },
                        "value": {
                            "old": "false",
                            "new": "true"
                        },
                        "permissions": {
                            "old": "{readPermissions=[], writePermissions=[rnd_admin]}",
                            "new": "{readPermissions=[], writePermissions=[rnd_admin, conf_admin]}"
                        }
                    },
                    "product_name": "perfecto"
                },
                "sort": [
                    1764847044983
                ]
            },
            {
                "_index": "perfecto-000058",
                "_id": "_-QT6ZoB-PNmllGNi5kd",
                "_score": null,
                "_source": {
                    "status": "SUCCESS",
                    "service": "feature-settings-service",
                    "timestamp": "2025-12-04T11:16:03.158Z",
                    "resource_id": "scriptless-mobile-ide.ai-validations.feedback.email.group",
                    "actor_type": "user",
                    "@timestamp": "2025-12-04T11:16:03.000Z",
                    "@version": "1",
                    "region": "01",
                    "description": "Updating a system setting",
                    "action": "Update system setting",
                    "actor_id": "offline_job",
                    "resource_type": "config",
                    "tags": [
                        "tail.0"
                    ],
                    "trace_id": "ed6b797ce28c46be8722126ace036678",
                    "custom_fields": {
                        "name": "scriptless-mobile-ide.ai-validations.feedback.email.group"
                    },
                    "hostname": "2477096963f1",
                    "tenant_id": "operator",
                    "module": "system-settings",
                    "changes": {
                        "value": {
                            "old": "ai-perfecto-feedback@perforce.com",
                            "new": "perfecto.noreply@perforce.com"
                        }
                    },
                    "product_name": "perfecto"
                },
                "sort": [
                    1764846963158
                ]
            }
        ]
    },
    "status": 200
}

Error response

Field	Description
`userMessage`	`Error message` is shown
`developerMessage`	You can send this value to Perfecto support to check errors and see if further investigation is needed

Copy

JSON response

[
    {
        "userMessage":"ERROR_MESSAGE",
        "developerMessage": "1-63dbebb1-4521fab52df9f41a578221c8"
    }
]

Sample Error response

A customer tried to search for audit data when Audit search functionality is not enabled

Copy

JSON response

[
    {
        "userMessage": "Audit search is not enabled for this tenant. Please contact Perfecto administrator to enable audit search logs.",
        "developerMessage": "0d53607ba9ec46c39e1b2657ca83cf90"
    }
]

User does not have permission to get audit logs:

Copy

JSON response

[
    {
        "userMessage": "operation for getting audit logs is not permitted for current user",
        "developerMessage": "e47ee6ea72b3406ea054e7fbe088914b"
    }
]

Passing status other than success/failure:

Copy

JSON response

[
    {
        "userMessage": "Status should be success or failure",
        "developerMessage": "7317780cee0443af842944180832e96c"
    }
]

Passing resourceType other than allowed values:

Copy

JSON response

[
    {
        "userMessage": "Resource type should be one of the resource types. Please refer to the documentation for the complete list.",
        "developerMessage": "aa2788defb2d4dad8f586863bddc7269"
    }
]

Passing action other than allowed values:

Copy

JSON response

[
    {
        "userMessage": "Action should be one of the allowed actions. Please refer to the documentation for the complete list.",
        "developerMessage": "aa2788defb2d4dad8f586863bddc7269"
    }
]

Passing description other than allowed values:

Copy

JSON response

[
    {
        "userMessage": "Description should be one of the allowed descriptions. Please refer to the documentation for the complete list.",
        "developerMessage": "aa2788defb2d4dad8f586863bddc7269"
    }
]

Passing actorType other than allowed values:

Copy

JSON response

[
    {
        "userMessage": "Actor type should be either 'admin' or 'user'",
        "developerMessage": "aa2788defb2d4dad8f586863bddc7269"
    }
]

Passing timestamp in another format:

Copy

JSON response

[
    {
        "userMessage": "Timestamp should be in ISO8601 format",
        "developerMessage": "aa2788defb2d4dad8f586863bddc7269"
    }
]