The docs are moving!
Find us at our new Help Center where we've combined our documentation and knowledgebase articles in one easy-to-search location.
We aren't updating the Developer Portal anymore, except for the Element Docs — all updates happen in the Help Center. We're retiring the Developer Portal as you know it in:
Usage APIs
The Usage API method calls allow you to track Element activity within your Cloud Elements Service Account. Services include retrieving logs, analytics, API calls, response times, and status calls. Stay on top of your Elements with the Usage APIs.
In order to access the Usage APIs, you must sign up for Cloud Elements Service. You will need your Organization and User Secrets to make success Usage API calls. These are generated for you when you sign up for our service. Details on how to sign up and where to find your Organization and User Secrets are documented in the next section.
WHERE TO FIND THE USAGE APIS
The Usage APIs can be accessed via Cloud Elements at: https://console.cloud-elements.com/elements/jsp/login.jsp. The console provides a Graphical User Interface (GUI) environment that formats data returned by each of the API calls into graphs. An example can be seen below. The Usage APIs can also be integrated right into you app.
SIGN UP FOR THE CLOUD ELEMENTS SERVICE
To sign up for the Cloud Elements service, using a web browser, go to https://console.cloud-elements.com/elements/jsp/signup.jsp.
Sign up with Google, GitHub or fill out a short form to create a new account with Cloud Elements. If you choose not to use Google or GitHub to sign up, you will be asked to validate your new account via a confirmation link that will be sent to your email. You will reset your password to one of your choice after your initial login.
After completing this process, click “Secrets” in the top right corner of your dashboard as shown.
Copy your User and Organization Secrets. They are needed to create a connection or “Element Instance”.
NOTE: If you ever need to reset your Secrets, this action can be done by clicking on “My Settings” which will take you to your profile.
How to Use the Usage APIs
This document will show examples of how to retrieve usage data. NOTE, not all supported calls are displayed - this is just a sample.
GET/usage
Retrieve the usage logs for your account.
Below is an example cURL command demonstrating the GET /usage API call and successful response. Please make sure your quotes are straight in the cURL command.
curl -X GET
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
'https://api.cloud-elements.com/elements/api-v2/usage'
Input Definitions:
`Input Definitions hub optional The name of the hub. eg documents, messaging,crm. This is an optional input.
keys[] optional
A list of element keys. eg, keys[]=dropbox&keys[]=googledrive&keys[]=box
tags[] optional
A list of tags. eg, tags[]=development&tags[]=qa
status optional
Filter by Status either SUCCCESS or FAILED
from optional
Start time in the ISO8601 format '2014-04-14'T'00:00:00-4:00'
if not supplied defaults to 7 days ago
to optional
Start time in the ISO8601 format <br> eg '2014-04-14'T'00:00:00-4:00'
if not supplied defaults current time
searchText optional
Text to match in the usage.
pageOffset optional
Starting page offset for pagination.
Defaults to 0
pageSize optional
Number of records per page
defaults to 100`
Example of Successful Response:
[
{
"id": "53e6df56e4b067fd19a9d69f",
"requestStatus": "SUCCESS",
"elementName": "GitHub OAuth",
"elementKey": "githuboauth",
"accountId": 1,
"instanceName": "production 2",
"usageDate": "2014-08-10T03:02:34.053+00:00",
"userId": 1,
"processTime": 992,
"requestURI": "/elements/api-v1/oauth/1/authenticate",
"requestIP": "172.31.28.13",
"elementTags": "production",
"elementApi": "authenticate",
"companyId": 1
},
{
"id": "53e6e0c8e4b067fd19a9d6ab",
"requestStatus": "SUCCESS",
"elementName": "GitHub OAuth",
"elementKey": "githuboauth",
"accountId": 1,
"instanceName": "production 2",
"usageDate": "2014-08-10T03:02:32.412+00:00",
"userId": 1,
"processTime": 317,
"requestURI": "/elements/api-v1/oauth/getRequestToken",
"requestIP": "172.31.28.13",
"elementTags": "production",
"elementApi": "getRequestToken",
"companyId": 1
}
]
GET /usage/analytics/activity
Retrieve the number of element API calls within a given date/time range.
Below is an example cURL command demonstrating the GET /usage/analytics/activity API call and successful response. Please make sure your quotes are straight in the cURL command.
curl -X GET
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
-H 'Content-Type:application/json'
-H 'Cache-Control:no-cache'
'https://api.cloud-elements.com/elements/api-v2/usage/analytics/activity?from=2014-03-01T00:00:00Z&to=2014-04-01T00:00:00Z&interval=day'
Input Definitions
`from mandatory
Start time in the ISO8601 format eg '2014-04-14'T'00:00:00-4:00'
to mandatory
End time in the ISO8601 format eg '2014-04-14'T'00:00:00-4:00'
interval optional
The Interval is sent in order to return data. The interval may be set to the
year, quarter, month, week, day, hour, minute, or second. If the interval is
not supplied, the API call calculates the interval based on time difference.`
Example of Successful Response – example has been truncated.
[
{
"timestamp": "2014-03-01T00:00:00.000Z",
"count": 5760
},
{
"timestamp": "2014-03-02T00:00:00.000Z",
"count": 5762
},
{
"timestamp": "2014-03-03T00:00:00.000Z",
"count": 5837
},
{
"timestamp": "2014-03-04T00:00:00.000Z",
"count": 5767
},
{
"timestamp": "2014-03-05T00:00:00.000Z",
"count": 5923
},
{
"timestamp": "2014-03-06T00:00:00.000Z",
"count": 5763
},
{
"timestamp": "2014-03-15T00:00:00.000Z",
"count": 5760
},
{
"timestamp": "2014-03-28T00:00:00.000Z",
"count": 5335
},
{
"timestamp": "2014-03-31T00:00:00.000Z",
"count": 5325
},
{
"timestamp": "2014-04-01T00:00:00.000Z",
"count": 0
}
…
]
GET /usage/analytics/activity/elements
Retrieve the number of element API calls for each element within a given date/time range.
Below is an example cURL command demonstrating the GET /usage/analytics/activity/elements API call and successful response. Please make sure your quotes are straight in the cURL command.
curl -X GET
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
-H 'Content-Type:application/json'
-H 'Cache-Control:no-cache'
'https://api.cloud-elements.com/elements/api-v2/usage/analytics/activity/elements?from=2014-03-01T00:00:00Z&to=2014-04-01T00:00:00Z&interval=month'
Input Definitions:
`from mandatory Start time in the ISO8601 format eg '2014-04-14'T'00:00:00-4:00'
to mandatory
End time in the ISO8601 format eg '2014-04-14'T'00:00:00-4:00'
interval optional
The Interval is sent in order to return data. The interval may be set to the
year, quarter, month, week, day, hour, minute, or second. If the interval is
not supplied, the API call calculates the interval based on time difference.`
Example Successful Response:
[
{
"sendgrid": 3087,
"timestamp": "2014-03-01T00:00:00.000Z",
"count": 178886,
"githuboauth": 111,
"twilio": 175688
},
{
"timestamp": "2014-04-01T00:00:00.000Z",
"count": 0
}
]
GET /usage/analytics/times
Retrieve the response times of element API calls within a given date/time range.
Below is an example cURL command demonstrating the GET /usage/analytics/times API call and successful response. Please make sure your quotes are straight in the cURL command.
curl -X GET
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
-H 'Content-Type:application/json'
-H 'Cache-Control:no-cache'
'https://api.cloud-elements.com/elements/api-v2/usage/analytics/times?from=2014-07-01T00:00:00Z&to=2014-08-01T00:00:00Z&interval=day'
Input Definitions
`from mandatory Start time in the ISO8601 format eg '2014-04-14'T'00:00:00-4:00'
to mandatory
End time in the ISO8601 format eg '2014-04-14'T'00:00:00-4:00'
interval optional
The Interval is sent in order to return data. The interval may be set to the
year, quarter, month, week, day, hour, minute, or second. If the interval is
not supplied, the API call calculates the interval based on time difference.`
Example of Successful Response: Response has been truncated.
[
{
"min": 434,
"timestamp": "2014-07-01T00:00:00.000Z",
"max": 1512,
"count": 12,
"avg": 1069.4166666666667
},
{
"min": 234,
"timestamp": "2014-07-02T00:00:00.000Z",
"max": 1698,
"count": 2,
"avg": 966
},
{
"min": 186,
"timestamp": "2014-07-03T00:00:00.000Z",
"max": 2927,
"count": 11,
"avg": 860
},
{
"min": 222,
"timestamp": "2014-07-04T00:00:00.000Z",
"max": 1255,
"count": 5,
"avg": 513.2
},
{
"min": 242,
"timestamp": "2014-07-30T00:00:00.000Z",
"max": 4471,
"count": 10,
"avg": 2533.7
},
{
"min": 226,
"timestamp": "2014-07-31T00:00:00.000Z",
"max": 3790,
"count": 7,
"avg": 1631.857142857143
},
{
"timestamp": "2014-08-01T00:00:00.000Z",
"count": 0
}
…
]
GET /usage/analytics/statuses
Retrieve the number of successes and failures of element API calls within a given date/time range.
Below is an example cURL command demonstrating the GET /usage/analytics/statuses API call and successful response. Please make sure your quotes are straight in the cURL command.
curl -X GET
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
-H 'Content-Type:application/json'
-H 'Cache-Control:no-cache'
'https://api.cloud-elements.com/elements/api-v2/usage/analytics/statuses?from=2014-08-01T00:00:00Z&to=2014-08-27T00:00:00Z&interval=day'
Input Definitions:
`from mandatory Start time in the ISO8601 format eg '2014-04-14'T'00:00:00-4:00'
to mandatory
End time in the ISO8601 format eg '2014-04-14'T'00:00:00-4:00'
interval optional
The Interval is sent in order to return data. The interval may be set to the
year, quarter, month, week, day, hour, minute, or second. If the interval is
not supplied, the API call calculates the interval based on time difference.`
Successful Example Response: Response has been truncated.
[
{
"timestamp": "2014-07-01T00:00:00.000Z",
"count": 12,
"failed": 0,
"success": 12
},
{
"timestamp": "2014-07-02T00:00:00.000Z",
"count": 2,
"failed": 0,
"success": 2
},
{
"timestamp": "2014-07-03T00:00:00.000Z",
"count": 11,
"failed": 0,
"success": 11
},
{
"timestamp": "2014-07-04T00:00:00.000Z",
"count": 5,
"failed": 1,
"success": 4
},
{
"timestamp": "2014-07-28T00:00:00.000Z",
"count": 13,
"failed": 2,
"success": 11
},
{
"timestamp": "2014-08-01T00:00:00.000Z",
"count": 0,
"failed": 0,
"success": 0
}
…
]
GET /usage/{id}
Retrieve the usage record by id
Below is an example cURL command demonstrating the GET /usage/{id} API call and successful response. Please make sure your quotes are straight in the cURL command.
curl -X GET
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
-H 'Content-Type:application/json'
-H 'Cache-Control:no-cache'
'https://api.cloud-elements.com/elements/api-v2/usage/id%20of%20log'
Input Definitions:
`id - id of the log record. In the example response, the id is:
53e6e0c8e4b067fd19a9d6ab. You would put this id at the end of the URL above in
place of id%20of%20log`
Example of Successful Response:
{
"id": "53e6e0c8e4b067fd19a9d6ab",
"requestStatus": "SUCCESS",
"elementName": "GitHub OAuth",
"elementKey": "githuboauth",
"accountId": 1,
"instanceName": "production 2",
"usageDate": "2014-08-10T03:02:32.412+00:00",
"userId": 1,
"processTime": 317,
"requestURI": "/elements/api-v1/oauth/getRequestToken",
"requestIP": "172.31.28.13",
"elementTags": "production",
"elementApi": "getRequestToken",
"companyId": 1
}
If you need any support integrating our APIs, please let us know. You can email or give us a call at +1.866.830.3456. We will do our best to get back to you within 24 hours. Your success is our success.