REST API for Documents

Get File Accesses

get

/documents/api/1.2/files/{fileId}/accesses

Get information on which users have accessed the specified file.

Request

Supported Media Types

application/json
application/xml

Path Parameters

fileId: string

Globally unique identifier (GUID) for the file.

Query Parameters

limit(optional): string

Specify the maximum number of accesses to return. Use this parameter to specify how many items to include on a single page of results. The default is 200.
offset(optional): string

Specify the point at which to begin the list of items from the complete set of items returned for the action. If you do not specify an offset, the returned items begin with the first item in the item list (offset=0).
orderBy(optional): string
The results can be sorted by the fields below. The sort order can be defined as ascending (asc) or descending (desc). The default sort order is ascending.
- accessedBy sorts by the user who initiated the activity.
- version sorts by version of the item on which activity occurred.
- accessType sorts by the type of the access (for example: preview, download).
- size sorts by the size of the item accesses.
- accessedTime sorts by the time of the access.
- clientIP sorts by IP address of the client on which this activity was initiated.
- errorCode sorts by the status code of the activity.

Header Parameters

accessToken(optional): string

Applink access token authorizing the current user to access the parent folder or this file. This parameter is mandatory if appLinkID is used. It can be used as accessToken or AccessToken.
appLinkID(optional): string

Applink ID authorizing the current user to access the parent folder or this file. Any time the parameter appLinkID is used, a parameter accessToken must be provided as well. To work, this applink must have at least the contributor role granted. It can be used as appLinkID or AppLinkID.
dAccessCode(optional): string

Access code needed to use protected public links. It needs to be sent as part of a Cookie header in the following format: dAccessCode-<linkID>=<passcodeValue>
linkID(optional): string

Public link ID of a public link authorizing the current user to access this file. It can be used as linkID or LinkID.

Response

Supported Media Types

application/json
application/xml

200 Response

The request was fulfilled.

Root Schema : FileAccessesResponse

Type: object

Show Source

count(optional): string

The number of accesses returned.
errorCode(optional): string

An error code of zero (0) indicates no errors.
hasMore(optional): string

Indicates if all accesses were returned; if all the accesses were returned, this is zero (0).
items(optional): array items

List of File Accesses.
totalCount(optional): string

The total number of accesses for the item.

{
    "description":"",
    "properties":{
        "count":{
            "type":"string",
            "description":"The number of accesses returned."
        },
        "errorCode":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        },
        "hasMore":{
            "type":"string",
            "description":"Indicates if all accesses were returned; if all the accesses were returned, this is zero (0)."
        },
        "totalCount":{
            "type":"string",
            "description":"The total number of accesses for the item."
        },
        "items":{
            "type":"array",
            "description":"List of File Accesses.",
            "items":{
                "$ref":"#/definitions/FileAccessItemsDefinition"
            }
        }
    }
}

Nested Schema : items

Type: array

List of File Accesses.

Show Source

Array of: object FileAccessItemsDefinition

{
    "type":"array",
    "description":"List of File Accesses.",
    "items":{
        "$ref":"#/definitions/FileAccessItemsDefinition"
    }
}

Nested Schema : FileAccessItemsDefinition

Type: object

Show Source

accessedBy(optional): object User

User information
accessedTime(optional): string

Date the item was accessed.
accessType(optional): string

Type of the access (for example#58; preview, download).
clientIP(optional): string

The client IP that accessed the file
errorCode(optional): string

An error code of zero (0) indicates no errors accessing the file.
id(optional): string

Globally unique identifier (GUID) for the file that was accessed.
refererURL(optional): string

The referring URL of the access.
size(optional): string

The size of the accessed file.
version(optional): string

Version of the file that was accessed.

{
    "description":"",
    "properties":{
        "accessType":{
            "type":"string",
            "description":"Type of the access (for example#58; preview, download)."
        },
        "accessedTime":{
            "type":"string",
            "description":"Date the item was accessed."
        },
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the file that was accessed."
        },
        "version":{
            "type":"string",
            "description":"Version of the file that was accessed."
        },
        "accessedBy":{
            "$ref":"#/definitions/User"
        },
        "errorCode":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors accessing the file."
        },
        "clientIP":{
            "type":"string",
            "description":"The client IP that accessed the file"
        },
        "refererURL":{
            "type":"string",
            "description":"The referring URL of the access."
        },
        "size":{
            "type":"string",
            "description":"The size of the accessed file."
        }
    }
}

Nested Schema : User

Type: object

User information

Show Source

displayName(optional): string

The display name for the user.
id(optional): string

Globally unique identifier (GUID) for the user.
loginName(optional): string

The login name for the user.
type(optional): string

Item type user.

{
    "description":"User information",
    "properties":{
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the user."
        },
        "displayName":{
            "type":"string",
            "description":"The display name for the user."
        },
        "loginName":{
            "type":"string",
            "description":"The login name for the user."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>user</code>."
        }
    }
}

Example Response (application/json)

{
    "count":"1",
    "errorCode":"0",
    "hasMore":"0",
    "totalCount":"1",
    "type":"access",
    "items":[
        {
            "type":"file",
            "accessType":"download",
            "accessedTime":"2017-05-02T21:23:18.000Z",
            "id":"D574378400573ED9D62B3195T0000000000100000001",
            "version":"1",
            "accessedBy":{
                "displayName":"User AA",
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "loginName":"userAALoginName",
                "type":"user"
            },
            "errorCode":"0",
            "clientIP":"10.10.82.114",
            "refererURL":"https://service1-tenant1:19200/documents/fileview/D1EEF28A920A342E8EC0E39645B3E9DD6490EF9D4696/_Mugs.jpg",
            "size":"53834"
        }
    ]
}

400 Response

Request parameters are not formatted correctly.

403 Response

Forbidden if the user does not have read permission.

404 Response

File ID is not found.

Examples

The following example gets information about the accesses (downloads and previews) for a file.

GET .../files/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/accesses

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "4",
    "errorCode": "0",
    "hasMore": "0",
    "totalCount": "4",
    "type": "access",
    "items": [
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:47:24Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
            	"displayName": "User AA",
		"id": "U0EAA20910FAF3052ACB79E4T00000000001",
		"loginName": "userAALoginName",
		"type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "download",
            "accessedTime": "2017-05-03T21:47:06Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
            	"displayName": "User AA",
		"id": "U0EAA20910FAF3052ACB79E4T00000000001",
		"loginName": "userAALoginName",
		"type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/folder/F9D24A8073BF47E5B9B1CAE345B3E9DD64902A090B2E/_accessed",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:46:45Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
            	"displayName": "User AA",
		"id": "U0EAA20910FAF3052ACB79E4T00000000001",
		"loginName": "userAALoginName",
		"type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:44:21Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
            	"displayName": "User AA",
		"id": "U0EAA20910FAF3052ACB79E4T00000000001",
		"loginName": "userAALoginName",
		"type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        }
    ]
}

Example 2

The following example gets information about the accesses (downloads and previews) for a file, sorted by accessType. Note that the "preview" types are listed first.

GET .../files/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/accesses?orderBy=accessType

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "4",
    "errorCode": "0",
    "hasMore": "0",
    "totalCount": "4",
    "type": "access",
    "items": [
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:44:21Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
            	"displayName": "User AA",
		"id": "U0EAA20910FAF3052ACB79E4T00000000001",
		"loginName": "userAALoginName",
		"type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:47:24Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
            	"displayName": "User AA",
		"id": "U0EAA20910FAF3052ACB79E4T00000000001",
		"loginName": "userAALoginName",
		"type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:46:45Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
            	"displayName": "User AA",
		"id": "U0EAA20910FAF3052ACB79E4T00000000001",
		"loginName": "userAALoginName",
		"type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "download",
            "accessedTime": "2017-05-03T21:47:06Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
            	"displayName": "User AA",
		"id": "U0EAA20910FAF3052ACB79E4T00000000001",
		"loginName": "userAALoginName",
		"type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/folder/F9D24A8073BF47E5B9B1CAE345B3E9DD64902A090B2E/_accessed",
            "size": "53834"
        }
    ]
}

Example 3

The following example gets information about the accesses (downloads and previews) for a file, sorted by accessType in ascending order, and limited to 2. Note that only 2 items are returned with count, hasMore, and totalCount set appropriately. The download types are listed first.

GET .../files/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/accesses?orderBy=accessType?orderBy=accessType:asc&limit=2

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "2",
    "errorCode": "0",
    "hasMore": "1",
    "totalCount": "4",
    "type": "access",
    "items": [
        {
            "type": "file",
            "accessType": "download",
            "accessedTime": "2017-05-03T21:47:06Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
            	"displayName": "User AA",
		"id": "U0EAA20910FAF3052ACB79E4T00000000001",
		"loginName": "userAALoginName",
		"type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/folder/F9D24A8073BF47E5B9B1CAE345B3E9DD64902A090B2E/_accessed",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:47:24Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
            	"displayName": "User AA",
		"id": "U0EAA20910FAF3052ACB79E4T00000000001",
		"loginName": "userAALoginName",
		"type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        }
    ]
}

Example 4

The following example gets information about the accesses (downloads and previews) for a file. The example uses an applink ID because this file is under a folder structure not owned by or shared with the current user. The applink ID and access token are submitted in the request header.

GET .../files/DED694950C14AFF280419F9AB5D17B95F47087F4E518/accesses

Request Header

appLinkID: LF5Bxj4TPo_p4n4qWn0tbKTicR2cTUJKv7X_ng9E7ry93rRuDokPqS1d6-wKwhb_wtcGYFDsI_cNMxeKQ-HR-FXQhiVoGRTYM_MPZY8qpICfYU94mmnMjM_cvsRhKMzc0NJgvwEJfqqDwPsAVrhc8cmg== 
accessToken: 352FpiMmW66PeYI1Gh5b83I9CXRwZhLfYAu4TXdqpzD8uNKUBMZVVJ3ZvivUW8kQ

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "1",
    "errorCode": "0",
    "hasMore": "0",
    "totalCount": "1",
    "type": "access",
    "items": [
        {
            "type": "file",
            "accessType": "download",
            "accessedTime": "2017-06-26T17:38:44Z",
            "id": "DED694950C14AFF280419F9AB5D17B95F47087F4E518",
            "version": "2",
            "accessedBy": {
                "displayName": "User BB",
                "id": "U5083EA1954687218BA6C3D9B5D17B95F470",
                "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470",
                "type": "user"
            },
            "errorCode": "-25",
            "errorMessage": "Unable to download file. Access token for app link has expired.",
            "clientIP": "10.154.128.31",
            "size": "29"
        }
    ]
}

Example 5

The following example does not return information about the accesses because the file ID is not valid.

GET ...files/F8BDBD5812C1C10E3E5C1A1C45B3E9DD649028853801/accesses

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 404

JSON Response

{
    "errorCode": "-16",
    "errorKey": "!csActivitesGetHistoryError!csSecurityValidationFailed!csFldDoesNotExist,DF1D474F24FCE3A517F69D7F45B3E9DD64909ED47144!csUnprivilegedSystemError",
    "errorMessage": "Unable to get history of activities. Security validation failed. 'DF1D474F24FCE3A517F69D7F45B3E9DD64909ED47144' does not exist. The error was caused by an internally generated issue. The error has been logged.",
    "errorType": "file",
    "id": "DF1D474F24FCE3A517F69D7F45B3E9DD64909ED47144",
    "title": "Unable to get history of activities. Security validation failed. 'DF1D474F24FCE3A517F69D7F45B3E9DD64909ED47144' does not exist. The error was caused by an internally generated issue. The error has been logged.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 6

The following example does not return information about the accesses because the user does not have access to the specified file ID.

GET ...files/D1C9B4DB1F9D7632AA68A7B845B3E9DD64909ED4714F/accesses

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 403

JSON Response

JSON Response
{
    "errorCode": "-20",
    "errorKey": "!csActivitesGetHistoryError!csCloudItemInsufficientPrivileges,tenant1.cecsuser4,fFileGUID:D1C9B4DB1F9D7632AA68A7B845B3E9DD64909ED4714F,GET_ACTIVITY_HISTORY",
    "errorMessage": "Unable to get history of activities. User 'User AA' has insufficient privilege to access fFileGUID:D1C9B4DB1F9D7632AA68A7B845B3E9DD64909ED4714F with service GET_ACTIVITY_HISTORY.",
    "errorType": "file",
    "id": "D1C9B4DB1F9D7632AA68A7B845B3E9DD64909ED4714F",
    "title": "Unable to get history of activities. User 'User AA' has insufficient privilege to access fFileGUID:D1C9B4DB1F9D7632AA68A7B845B3E9DD64909ED4714F with service GET_ACTIVITY_HISTORY.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}