User Action Logs

Get Recent Administrative Logs

get

Retrieves user activity logs from the last 30 days.

This endpoint fetches logs stored in PostgreSQL (recent logs within retention period). Logs older than 30 days are archived in S3 and must be accessed via the archived-download-urls endpoint.

Headers

Name	Type
Authorization*	HMAC {key}:{signature}:{nonce}:{timestamp}
Content-Type	application/json

Query Parameters

Parameter	Type	Required	Description
start_date	DateTime	Yes	Start date in ISO 8601 format. E.g., 2024-01-01T00:00:00Z
end_date	DateTime	Yes	End date in ISO 8601 format. Must be after start_date. E.g., 2024-01-31T23:59:59Z
action_type	String	No	Filter by action type. See action types list below
user_email	String	No	Filter by user email address
organization_machine_id	Integer	No	Filter by machine ID

Retention Policy

• Logs from the last 30 days are stored in PostgreSQL (fast querying)

• Logs older than 30 days are archived in S3

• If date range extends beyond 30 days, only the recent portion is returned

• Maximum 1000 logs returned per request

Action Types

Action Type	Description
machine_started	Machine was started
machine_stopped	Machine was stopped
machine_reset	Machine was reset to factory settings
machine_type_changed	Machine type was changed (upgrade/downgrade)
machine_external_access_created	External access token was created
machine_created	Machine was created
file_downloaded	File was downloaded
file_uploaded	File upload was completed
file_deleted	File or folder was deleted
folder_created	Folder was created
user_login	User logged in

Error Responses

Status	Description
400	Bad request (e.g., end_date is before start_date)

Response Fields

Field	Type	Description
logs	Array	Array of log entry objects
logs[].id	Integer	Log entry ID
logs[].action_type	String	Action type (see action types table above)
logs[].user_id	Integer	User ID who performed the action
logs[].user_email	String	Email address of user who performed the action
logs[].machine_id	Integer	Machine ID (organization_machine_id). null if action not related to a machine
logs[].metadata	Object	Additional metadata specific to the action type. Structure varies by action
logs[].created_at	String	ISO 8601 timestamp when log was created
logs[].updated_at	String	ISO 8601 timestamp when log was last updated
count	Integer	Total number of logs returned (max 1000)
start_date	String	Start date used in query (ISO 8601)
end_date	String	End date used in query (ISO 8601)
note	String	Optional note if date range extends beyond retention period

Metadata Examples by Action Type

• machine_started: { "machine_type_id": 1, "machine_type_name": "Standard", "region": "dublin" }

• machine_type_changed: { "old_machine_type_id": 1, "new_machine_type_id": 2, "machine_type_name": "Performance" }

• file_deleted: { "file_id": 123, "file_name": "document.pdf", "file_size": 1048576, "file_content_type": "application/pdf", "is_shared": false, "object_type": "file" }

• file_uploaded: { "file_id": 123, "file_name": "document.pdf", "file_size": 1048576 }

Response Example

{
  "logs": [
    {
      "id": 1,
      "action_type": "machine_started",
      "user_id": 123,
      "user_email": "[email protected]",
      "machine_id": 456,
      "metadata": {
        "machine_type_id": 1,
        "machine_type_name": "Standard",
        "region": "dublin"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 2,
      "action_type": "file_deleted",
      "user_id": 123,
      "user_email": "[email protected]",
      "machine_id": 456,
      "metadata": {
        "file_id": 789,
        "file_name": "document.pdf",
        "file_size": 1048576,
        "file_content_type": "application/pdf",
        "is_shared": false,
        "object_type": "file"
      },
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    }
  ],
  "count": 150,
  "start_date": "2024-01-01T00:00:00Z",
  "end_date": "2024-01-31T23:59:59Z"
}

Note

For logs older than 30 days, use the archived-download-urls endpoint. If the date range extends beyond the retention period, the response will include a note field indicating to use the archived endpoint.

Query parameters

start_datestringOptional

(Required) Start date. ISO 8601 format (e.g., 2024-01-01T00:00:00Z)

Example: 2024-01-01T00:00:00Z

end_datestringOptional

(Required) End date. ISO 8601 format. Must be after start_date.

Example: 2024-01-31T23:59:59Z

action_typestringOptional

(Optional) Action type filter. E.g., machine_started, machine_stopped, file_downloaded

user_emailstringOptional

(Optional) Filter by user email

organization_machine_idstringOptional

(Optional) Filter by machine ID

Responses

get

/organization-management/v1/user-action-logs

HTTPcURLJavaScriptPython

GET /organization-management/v1/user-action-logs HTTP/1.1
Host: api.vagon.io
Accept: */*

Get Archived Administrative Logs

get

Generates presigned S3 download URLs for archived logs older than 30 days.

This endpoint provides download URLs for logs that have been archived to S3. Logs are archived monthly, so each URL typically contains one month of logs.

Headers

Name	Type
Authorization*	HMAC {key}:{signature}:{nonce}:{timestamp}
Content-Type	application/json

Query Parameters

Parameter	Type	Required	Default	Description
start_date	DateTime	Yes	-	Start date in ISO 8601 format. Must be older than 30 days. E.g., 2023-01-01T00:00:00Z
end_date	DateTime	Yes	-	End date in ISO 8601 format. Must be older than 30 days. Must be after start_date. E.g., 2023-12-31T23:59:59Z
expires_in	Integer	No	600	Presigned URL validity duration in seconds. Default: 600 (10 minutes). Maximum recommended: 3600 (1 hour)

Restrictions

• Can only be used for logs older than 30 days

• Use the main /user-action-logs endpoint for logs from the last 30 days

• Date range must be entirely within the archived period

Validation

• end_date must be after start_date

• Both dates must be older than 30 days

• Both dates must be in the past

Error Responses

Status	Description
400	Bad request.

Response Fields:

Field	Type	Description
download_urls	Array	Array of presigned S3 download URLs. Each URL typically contains one month of logs
download_urls[]	String	Presigned S3 URL for downloading archived log file. URL expires after expires_in seconds
count	Integer	Number of download URLs generated
start_date	String	Start date used in query (ISO 8601)
end_date	String	End date used in query (ISO 8601)

Response Example:

{
  "download_urls": [
    "https://s3.amazonaws.com/vagon-logs/org-123/2023-01.json.gz?X-Amz-Signature=abc123...&X-Amz-Expires=600",
    "https://s3.amazonaws.com/vagon-logs/org-123/2023-02.json.gz?X-Amz-Signature=def456...&X-Amz-Expires=600",
    "https://s3.amazonaws.com/vagon-logs/org-123/2023-03.json.gz?X-Amz-Signature=ghi789...&X-Amz-Expires=600"
  ],
  "count": 12,
  "start_date": "2023-01-01T00:00:00Z",
  "end_date": "2023-12-31T23:59:59Z"
}

Usage Instructions:

1. Download Files: Make HTTP GET requests to each URL in download_urls array

2. File Format: Files are in .json.gz format (gzip-compressed JSON)

3. Content: Each file typically contains one month of logs in JSON format

4. Decompression: Decompress the .gz files to get JSON data

5. URL Expiration: URLs expire after expires_in seconds (default 10 minutes)

6. Download Timing: Download all URLs promptly after receiving the response

File Structure: Each downloaded file contains an array of log objects with the same structure as the main endpoint response.

Query parameters

start_datestringOptional

(Required) Start date. Must be older than 30 days.

Example: 2023-01-01T00:00:00Z

end_datestringOptional

(Required) End date. Must be older than 30 days.

Example: 2023-12-31T23:59:59Z

expires_inintegerOptional

(Optional) URL validity duration (seconds). Default: 600 (10 minutes)

Example: 600

Responses

get

/organization-management/v1/user-action-logs/archived-download-urls

HTTPcURLJavaScriptPython

GET /organization-management/v1/user-action-logs/archived-download-urls HTTP/1.1
Host: api.vagon.io
Accept: */*