History Exports

A History Export is a resource on the API that is used to export historical action (history) logs.

All queries against the archive must be submitted as Exports. (Even our Web UI creates an Export behind the scenes.)

We use Amazon Athena behind the scenes for processing these queries, and as such, have powerful search capabilities. We've done our best to expose search capabilities via this History Export API.

In any query field in this API, you may specify multiple values separated by commas. That means that commas cannot be searched for themselves, and neither can single quotation marks.

We do not currently partition data by date on the backend, so all queries result in a full scan of the entire data lake. This means that all queries will take about the same amount of time to complete, and we incur about the same cost per query internally. We don't typically bill our customers for these queries, assuming usage is occasional and manual.

If you intend to use this API for high volume or automated use, please contact us with more information about your use case. We may decide to change the backend data schema to match your use case more closely, and we may also need to charge an additional cost per query.

Example History Queries

  • History for a user: { "query_user_id": 123 }
  • History for a range of time: { "start_at": "2021-03-18 12:00:00", "end_at": "2021-03-19 12:00:00" }
  • History of logins and failed logins: { "query_action": "login,failedlogin" }
  • A Complex query: { "query_folder": "uploads", "query_action": "create,copy,move", "start_at": "2021-03-18 12:00:00", "end_at": "2021-03-19 12:00:00" }

Show History Export

SDK Method

HistoryExport.Find();

Return Object

HistoryExport

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
id
int64
Required		History Export ID.

Example Request

using FilesCom.Models;

try
{
    var historyExport = await HistoryExport.Find(id);
    // Operate on historyExport
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

Create History Export

SDK Method

HistoryExport.Create();

Return Object

HistoryExport

Authorization Requirement

Available to all authenticated keys or sessions.

Method Arguments

ArgumentDescription
user_id
int64		User ID. Provide a value of 0 to operate the current session's user.
start_at
string		Start date/time of export range.
end_at
string		End date/time of export range.
query_action
string		Filter results by this this action type. Valid values: create, read, update, destroy, move, login, failedlogin, copy, user_create, user_update, user_destroy, group_create, group_update, group_destroy, permission_create, permission_destroy, api_key_create, api_key_update, api_key_destroy, archived_delete
query_interface
string		Filter results by this this interface type. Valid values: web, ftp, robot, jsapi, webdesktopapi, sftp, dav, desktop, restapi, scim, office, mobile, as2, inbound_email, remote, inbound_s3
query_user_id
string		Return results that are actions performed by the user indicated by this User ID
query_file_id
string		Return results that are file actions related to the file indicated by this File ID
query_parent_id
string		Return results that are file actions inside the parent folder specified by this folder ID
query_path
string		Return results that are file actions related to paths matching this pattern.
query_folder
string		Return results that are file actions related to files or folders inside folder paths matching this pattern.
query_src
string		Return results that are file moves originating from paths matching this pattern.
query_destination
string		Return results that are file moves with paths matching this pattern as destination.
query_ip
string		Filter results by this IP address.
query_username
string		Filter results by this username.
query_failure_type
string		If searching for Histories about login failures, this parameter restricts results to failures of this specific type. Valid values: expired_trial, account_overdue, locked_out, ip_mismatch, password_mismatch, site_mismatch, username_not_found, none, no_ftp_permission, no_web_permission, no_directory, errno_enoent, no_sftp_permission, no_dav_permission, no_restapi_permission, key_mismatch, region_mismatch, expired_access, desktop_ip_mismatch, desktop_api_key_not_used_quickly_enough, disabled, country_mismatch, insecure_ftp, insecure_cipher, rate_limited
query_target_id
string		If searching for Histories about specific objects (such as Users, or API Keys), this parameter restricts results to objects that match this ID.
query_target_name
string		If searching for Histories about Users, Groups or other objects with names, this parameter restricts results to objects with this name/username.
query_target_permission
string		If searching for Histories about Permissions, this parameter restricts results to permissions of this level.
query_target_user_id
string		If searching for Histories about API keys, this parameter restricts results to API keys created by/for this user ID.
query_target_username
string		If searching for Histories about API keys, this parameter restricts results to API keys created by/for this username.
query_target_platform
string		If searching for Histories about API keys, this parameter restricts results to API keys associated with this platform.
query_target_permission_set
string		If searching for Histories about API keys, this parameter restricts results to API keys with this permission set.

Example Request

using FilesCom.Models;

var parameters = new Dictionary<string, object>();
parameters.Add("user_id", (Int64?) 1);

try
{
    var historyExport = await HistoryExport.Create(parameters);
    // Operate on historyExport
}
catch (FilesCom.NotAuthenticatedException e)
{
    Console.WriteLine($"Authentication Error Occurred ({e.GetType().Name}): " + e.Message);
}
catch (FilesCom.SdkException e)
{
    Console.WriteLine($"Unknown Error Occurred ({e.GetType().Name}): " + e.Message);
}

The HistoryExport Object

Some of the methods above return a HistoryExport object. The attributes of this object are listed below.

AttributeDescription
id
int64		History Export ID
history_version
string		Version of the history for the export.
start_at
date-time		Start date/time of export range.
end_at
date-time		End date/time of export range.
status
string		Status of export. Will be: building, ready, or failed
query_action
string		Filter results by this this action type. Valid values: create, read, update, destroy, move, login, failedlogin, copy, user_create, user_update, user_destroy, group_create, group_update, group_destroy, permission_create, permission_destroy, api_key_create, api_key_update, api_key_destroy, archived_delete
query_interface
string		Filter results by this this interface type. Valid values: web, ftp, robot, jsapi, webdesktopapi, sftp, dav, desktop, restapi, scim, office, mobile, as2, inbound_email, remote, inbound_s3
query_user_id
string		Return results that are actions performed by the user indicated by this User ID
query_file_id
string		Return results that are file actions related to the file indicated by this File ID
query_parent_id
string		Return results that are file actions inside the parent folder specified by this folder ID
query_path
string		Return results that are file actions related to paths matching this pattern.
query_folder
string		Return results that are file actions related to files or folders inside folder paths matching this pattern.
query_src
string		Return results that are file moves originating from paths matching this pattern.
query_destination
string		Return results that are file moves with paths matching this pattern as destination.
query_ip
string		Filter results by this IP address.
query_username
string		Filter results by this username.
query_failure_type
string		If searching for Histories about login failures, this parameter restricts results to failures of this specific type. Valid values: expired_trial, account_overdue, locked_out, ip_mismatch, password_mismatch, site_mismatch, username_not_found, none, no_ftp_permission, no_web_permission, no_directory, errno_enoent, no_sftp_permission, no_dav_permission, no_restapi_permission, key_mismatch, region_mismatch, expired_access, desktop_ip_mismatch, desktop_api_key_not_used_quickly_enough, disabled, country_mismatch, insecure_ftp, insecure_cipher, rate_limited
query_target_id
string		If searching for Histories about specific objects (such as Users, or API Keys), this parameter restricts results to objects that match this ID.
query_target_name
string		If searching for Histories about Users, Groups or other objects with names, this parameter restricts results to objects with this name/username.
query_target_permission
string		If searching for Histories about Permissions, this parameter restricts results to permissions of this level.
query_target_user_id
string		If searching for Histories about API keys, this parameter restricts results to API keys created by/for this user ID.
query_target_username
string		If searching for Histories about API keys, this parameter restricts results to API keys created by/for this username.
query_target_platform
string		If searching for Histories about API keys, this parameter restricts results to API keys associated with this platform.
query_target_permission_set
string		If searching for Histories about API keys, this parameter restricts results to API keys with this permission set.
results_url
string		If status is ready, this will be a URL where all the results can be downloaded at once as a CSV.