/events

Query node logs for information, and optionally filter the response, for the following types of events:

  • File transfers (including status of in-progress transfers)
  • File creation, modification, and deletion
  • File permission creation, modification, and deletion
  • Filelock creation, modification, reversion, and deletion
Requirements
  • Available as of Enterprise Server version 3.6.0. /events/{id} is available as of version 3.7.3.
  • To query events on nodes version 3.7.4 and later, enable activity event logging on the node by running the following command:
    asconfigurator -x "set_server_data;activity_event_logging,true"
    Restart the asperanoded service to activate your change. On Linux, run the following command:
    # service asperanoded restart
  • As of version 3.8.0, activity_event_logging can be configured for individual access keys and overrides the setting on the node. If activity_event_logging is enabled for the access key, any Node API events associated with that access key are logged even if the node setting is false. If it is disabled for the access key, events are not logged for the access key even if activity_event_logging is enabled on the node.
Access Control
  • HTTP Basic Auth
    Provide Node API credentials or an access key ID and secret. Users can see any event in the same tenant space.
  • Bearer token
    Bearer token users can see any event associated with a file_id to which they have any permission.
Headers

All requests to this endpoint use the same headers.

Header Name Required Description Values
Content-Type Optional The format of the request data. application/json
Accept Optional The format of the response data. application/json
X-Aspera-AccessKey Required
(for bearer token authorization)
The access key ID that was used to create the bearer token. Access key ID.
Authorization Required
(for bearer token authorization)
The bearer token. "Bearer token_string"

Endpoint Actions

Get Event Information for the Node

Get a full or filtered list of event information for the node, restricted to the events to which the user has access.

URL
GET https://{domain}:9092/events

Sample Requests
  • Get events for the current iteration token:
    curl -i -u user:secret -X GET https://{domain}:9092/events?after_time=2999-12-31T23:53:40Z
  • Get no more than 25 upload.started events that occurred after the specified time or iteration token (whichever is later).
    curl -i -u user:secret -X GET https://{domain}:9092/events?after_time=2015-09-11T23:53:40Z&iteration_token=2&count=10&type=upload.started

Query Parameters
Parameter Type Description Values
after_time String Get events that occurred after the specified time. If both after_time and iteration_token are specified, the most recent of those two attributes is used to determine which events are returned in the response. Time in ISO format.
iteration_token String Get events that occurred after the specified iteration token. The iteration token defines a specific time in the log; it is generated by a previous request and returned in the LINK header. The same iteration token is reported to different applications as long as they are querying the same server. Token string
count Unsigned integer Get no more than the specified number of events. If the number of events exceed count, then the oldest events are returned. Calling /events again with the returned HTTP link header returns the next oldest set. Number
type String Get events that match the type and subtype. Only one type can be specified at a time. To retrieve multiple types, use a glob pattern as a value for type_glob[]. If no types are specified, all event types are returned.
  • File event types: file.created, file.deleted, file.modified, file.moved
  • Permission event types: permission.created, permission.edited, permission.deleted, permission.modified, file.filelock.created (available as of 3.7.4), file.filelock.modified (available as of 3.7.4), file.filelock.deleted (available as of 3.7.4), file.filelock.reverted (available as of 3.7.4)
  • Transfer event types: transfer.started (includes download.started, upload.started); transfer.ended (includes download.ended, upload.ended).
type_glob[ ] String Get events that match the glob pattern, in which an asterisk (*) is a wildcard for all available subtypes.

Note: You can include only one glob pattern in a request, so if you need information for both file.* and permission.* events, for example, you must make two separate calls to the endpoint.

For example, file.* retrieves all , such as file.modified.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
Link: <https://localhost:9092/events?iteration_token=7>; rel="next"

[
{
    "id" : "1",
    "time" : "2018-02-13T00:03:11Z",
    "user_id" : "ASPERA_ACCESS_KEY_ADMIN",
    "types" : [
      "permission.created"
      ],
    "data" : {
      "id" : "1",
      "file_id" : "1",
      "access_id" : "user1",
      "access_type" : "user",
      "access_levels" : [
        "list",
        "read",
        "write",
        "delete",
        "mkdir",
        "rename",
        "preview"
      ],
      "tags" : null
      }
    },
    {
    "id" : "6",
    "time" : "2017-06-16T21:13:32Z",
    "user_id" : "ASPERA_ACCESS_KEY_ADMIN",
    "types" : [
      "download.started",
      "transfer.started"
      ],
    "data" : {
      "id" : "3",
      "user_id" : "ASPERA_ACCESS_KEY_ADMIN",
      "file_id" : "1",
      "direction" : "receive",
      "tags" : null,
      "remote_host" : "localhost",
      "ssh_port" : 22,
      "transfer_id" : "c03108d4-b81b-4800-a637-30a6402db908",
      "session_id" : "c03108d4-b81b-4800-a637-30a6402db908",
      "start_time_usec" : 1497647612000000,
      "end_time_usec" : null,
      "status" : "running",
      "error_code" : 0,
      "error_desc" : "",
      "files_completed" : 0,
      "bytes_transferred" : 0,
      "avg_rate_kbps" : 0,
      "target_rate_kbps" : 500000,
      "min_rate_kbps" : 0,
      "max_rate_kbps" : 0,
      "current_rate_kbps" : 0,
      "directories_completed" : 0
    }
  },
  {
    "id" : "7",
    "time" : "2017-06-16T21:13:34Z",
    "user_id" : "ASPERA_ACCESS_KEY_ADMIN",
    "types" : [
      "file.created"
    ],
    "data" : {
      "id" : "3",
      "path" : "/file.txt",
      "size" : 104857600,
      "type" : "file",
      "start_time" : "2017-06-16T21:13:32Z",
      "end_time" : "2017-06-16T21:13:33Z"
    }
  },
  {
    "id" : "8",
    "time" : "2017-06-16T21:13:34Z",
    "user_id" : "ASPERA_ACCESS_KEY_ADMIN",
    "types" : [
      "download.ended",
      "transfer.ended"
    ],
    "data" : {
      "id" : "3",
      "user_id" : "ASPERA_ACCESS_KEY_ADMIN",
      "file_id" : "1",
      "direction" : "receive",
      "tags" : null,
      "remote_host" : "localhost",
      "ssh_port" : 22,
      "transfer_id" : "c03108d4-b81b-4800-a637-30a6402db908",
      "session_id" : "c03108d4-b81b-4800-a637-30a6402db908",
      "start_time_usec" : 1497647612000000,
      "end_time_usec" : 1497647614059070,
      "status" : "completed",
      "error_code" : 0,
      "error_desc" : "",
      "files_completed" : 1,
      "bytes_transferred" : 104857600,
      "avg_rate_kbps" : 0,
      "target_rate_kbps" : 500000,
      "min_rate_kbps" : 0,
      "max_rate_kbps" : 0,
      "current_rate_kbps" : 0,
      "directories_completed" : 0
    }
  }
]

Status Codes and Errors
Code Description Notes
200 OK Success
400 Bad Request Error Request contains a formatting or syntax error.
500 Internal Server Error Error The server configuration is invalid.
Response
Element Type Description
id String The event ID.
time String The time of the event in ISO format.
user_id String The user ID of the user who caused the event.
types JSON An array of the event types associated with the event.
data JSON Information about the event, corresponding to the Node API endpoint response for the action, such as the transfer specification for transfers, or file information for permissions changes.

Get Event Information for a Specific Event

Get the event information for a specific event. User must have access to the event to get information.

URL
GET https://{domain}:9092/events/{id}

Sample Requests
curl -i -u user:secret -X GET https://{domain}:9092/events/{id} \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
    "id" : "1",
    "time" : "2018-02-13T00:03:11Z",
    "user_id" : "ASPERA_ACCESS_KEY_ADMIN",
    "types" : [
      "permission.created"
    ],
    "data" : {
      "id" : "1",
      "file_id" : "1",
      "access_id" : "user1",
      "access_type" : "user",
      "access_levels" : [
        "list",
        "read",
        "write",
        "delete",
        "mkdir",
        "rename",
        "preview"
      ],
      "tags" : null
      }
    }
]

Status Codes and Errors
Code Description Notes
200 OK Success
404 Not Found Error Invalid event ID.
500 Internal Server Error Error The server configuration is invalid.
Response
Element Type Description
id String The event ID.
time String The time of the event in ISO format.
user_id String The user ID of the user who caused the event.
types JSON An array of the event types associated with the event.
data JSON Information about the event, corresponding to the Node API endpoint response for the action, such as the transfer specification for transfers, or file information for permissions changes.
Video player

Video

×