Skip to content

GET /api/activities

Retrieve activity logs with advanced filtering and pagination.

Endpoint

GET /api/activities

Authentication

Requires API Key with read access (all keys have read access).

Authorization: Bearer <api-key>

Query Parameters

Parameter Type Required Description
search string No Advanced query string (generated by convertsearch). Sorting is expressed inline via an order by clause — see Sorting.
skip integer No Number of records to skip (default: 0)
take integer No Number of records to return (default: 25, max: 1000)

Request Example

curl -X GET "https://your-shield-host:8080/api/activities?search=QUERY%20order%20by%20timestamp%20desc&skip=0&take=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Format

Response Format 
{
  "items": [
    {
      "id": "activity-uuid",
      "timestamp": 1704067200,
      "url": "https://api.example.com/users",
      "hostname": "api.example.com",
      "username": "john.doe@company.com",
      "userGroup": "Engineering",
      "apps": [
        {
          "id": "app-uuid",
          "name": "Payment API"
        }
      ],
      "detected": true,
      "obfuscated": true,
      "blocked": false,
      "datatypesDetected": [
        {
          "type": "US_SSN",
          "name": "Social Security Number",
          "count": 2
        }
      ],
      "datatypesObfuscated": [
        {
          "type": "US_SSN",
          "name": "Social Security Number",
          "count": 2
        }
      ],
      "rules": [
        {
          "id": "rule-uuid",
          "name": "PII Protection Rule"
        }
      ],
      "contentType": "application/json",
      "icapMode": "REQMOD",
      "bodyLength": 2048,
      "httpStatusCode": 200
    }
  ],
  "count": 1543
}

Response Fields

Activity Metadata

Field Type Description
id string Unique activity identifier (UUID)
timestamp integer Unix timestamp (seconds since epoch)
url string Full request URL
hostname string Request hostname
username string Authenticated username (if available)
userGroup string User's group membership (if available)

Detection and Action

Field Type Description
detected boolean Whether sensitive data was detected
obfuscated boolean Whether data was masked
blocked boolean Whether request was blocked
bypassed boolean Whether scanning was bypassed

Policy Context

Field Type Description
apps object[] Matched applications
rules object[] Rules that matched this activity
datatypesDetected object[] Data types found in the request
datatypesObfuscated object[] Data types that were masked

Request Details

Field Type Description
contentType string HTTP Content-Type header
icapMode string REQMOD, RESPMOD, or API
bodyLength integer Request body size in bytes
httpStatusCode integer HTTP status code
clientIPAddress string Client IP address (if available)
clientDevice string Device type (if available)

Sorting

Sorting is part of the advanced query grammar, not a separate query parameter. Append an order by clause to the search string:

<filters> order by <field> <asc|desc>[, <field> <asc|desc>]*

Examples:

detected in (true) and timestamp >= '-7d' order by timestamp desc

timestamp >= '-1d' order by hostname asc, timestamp desc

The easiest way to produce a correctly formatted query is to pass an orderBy array to POST /api/activities/convertsearch — the converter appends the order by clause to the returned string for you.

Available sort fields:

  • timestamp
  • username
  • hostname
  • url
  • contentType
  • bodyLength
  • httpStatusCode

Note: Fields containing arrays (e.g., datatypesDetected, rules) cannot be used for sorting.

Pagination

Use skip and take to paginate through large result sets:

Python Example 
# Get first page (records 0-99)
page1 = requests.get(
    f"{BASE_URL}/api/activities",
    headers=HEADERS,
    params={"search": query, "skip": 0, "take": 100}
).json()

# Get second page (records 100-199)
page2 = requests.get(
    f"{BASE_URL}/api/activities",
    headers=HEADERS,
    params={"search": query, "skip": 100, "take": 100}
).json()

print(f"Total activities: {page1['count']}")

Complete Example

Example 
import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# Build query for last 24 hours, sorted newest first
query_request = {
    "simpleToAdvanced": {
        "timestamp": {"withinLast": {"days": 1, "hours": 0, "minutes": 0}},
        "orderBy": [{"field": "timestamp", "order": "desc"}]
    }
}

query = requests.post(
    f"{BASE_URL}/api/activities/convertsearch",
    headers=HEADERS,
    json=query_request
).json()["simpleToAdvanced"]

# Get activities (search already contains "order by timestamp desc")
response = requests.get(
    f"{BASE_URL}/api/activities",
    headers=HEADERS,
    params={
        "search": query,
        "skip": 0,
        "take": 100
    }
)

activities = response.json()

print(f"Found {activities['count']} activities")
print(f"Retrieved {len(activities['items'])} in this page")

# Process activities
for activity in activities["items"]:
    detected_types = [dt["type"] for dt in activity.get("datatypesDetected", [])]
    print(f"{activity['timestamp']}: {activity['url']} - Detected: {', '.join(detected_types)}")

Error Responses

Status Code Description Resolution
400 Invalid query syntax Verify query string format
401 Invalid or missing API key Check authentication
500 Server error Check Shield logs