API Reference – Reporting API – accountData()

Reporting API Method Documentation

©2009-2014 SocketLabs, Inc., Version 1.8, Last Edit: March 25, 2014

accountData

Synopsis:

Returns basic server information including current usage statistics.

Recommended Usage:

The accountData method is recommended for both automated monitoring and usage management of Email On-Demand accounts and servers.

For monitoring, regular calls to the accountData method could be used to record server utilization information in a local database. This enables a user to generate custom usage graphs and statistics beyond what is available through the Email On-Demand Control Panel.

Another use of the accountData method is to retrieve usage data for a server in order to detect when thresholds or throughput limitations are being reached. For example, this information would be tied to systems that send alerts when an account has used eighty percent of its monthly bandwidth. Another example could be the throttling of injected messages when the message limit is approaching a hard limit to avoid a failed injection scenario.

Request Information

URL:

https://api.socketlabs.com/v1/accountData

Response Format Types:

JSON, JSONP, XML or CSV

HTTP Method:

GET

Request Parameters:

serverId
Specifies the server ID to query. This parameter is required.
type
Specifies format of the response. May be set to JSON, JSONP, XML or CSV.

Example Request:

https://api.socketlabs.com/v1/accountData?serverid=0001&type=xml

Response Data Structures

Response Data Structure (JSON):

{
    "timestamp": "String",
    "object": {
        "ServerId": "Integer",
        "AccountId": "Integer",
        "PlanBillingPeriodStart": "String",
        "PlanBillingPeriodEnd": "String",
        "BillingPeriodStart": "String",
        "BillingPeriodEnd": "String",
        "BillingPeriodMessageCount": "Integer",
        "BillingPeriodBandwidthCountInBytes": "Integer",
        "BillingPeriodBandwidthCountInGigabytes": "Integer",
        "BillingPeriodApiCount": "Integer",
        "ApiAllowance": "Integer",
        "MaxApiAllowance": "Integer",
        "MessageAllowance": "Integer",
        "MaxMessageAllowance": "Integer",
        "BandwidthAllowanceInBytes": "Integer",
        "MaxBandwidthAllowanceInBytes": "Integer",
        "BandwidthAllowanceInGigabytes": "Double",
        "MaxBandwidthAllowanceInGigabytes": "Double",
        "IsOverApiAllowance": "Boolean",
        "IsOverBandwidthAllowance": "Boolean",
        "IsOverMessageAllowance": "Boolean"
    }
}

Response Data Structure (XML):

<response>
    <timestamp>Datetime</timestamp>
    <object>
        <ServerId>Integer</ServerId>
        <AccountId>Integer</AccountId>
        <PlanBillingPeriodStart>Date</PlanBillingPeriodStart>
        <PlanBillingPeriodEnd>Date</PlanBillingPeriodEnd>
        <BillingPeriodStart>Date</BillingPeriodStart>
        <BillingPeriodEnd>Date</BillingPeriodEnd>
        <BillingPeriodMessageCount>Integer</BillingPeriodMessageCount>
        <BillingPeriodBandwidthCountInBytes>Integer</BillingPeriodBandwidthCountInBytes>
        <BillingPeriodBandwidthCountInGigabytes>Integer</BillingPeriodBandwidthCountInGigabytes>
        <BillingPeriodApiCount>Integer</BillingPeriodApiCount>
        <ApiAllowance>Integer</ApiAllowance>
        <MaxApiAllowance>Integer</MaxApiAllowance>
        <MessageAllowance>Integer</MessageAllowance>
        <MaxMessageAllowance>Integer</MaxMessageAllowance>
        <BandwidthAllowanceInBytes>Integer</BandwidthAllowanceInBytes>
        <MaxBandwidthAllowanceInBytes>Integer</MaxBandwidthAllowanceInBytes>
        <BandwidthAllowanceInGigabytes>Double</BandwidthAllowanceInGigabytes>
        <MaxBandwidthAllowanceInGigabytes>Double</MaxBandwidthAllowanceInGigabytes>
        <IsOverApiAllowance>Boolean</IsOverApiAllowance>
        <IsOverBandwidthAllowance>Boolean</IsOverBandwidthAllowance>
        <IsOverMessageAllowance>Boolean</IsOverMessageAllowance>
    </object>
</response>

Response Data Structure (CSV):

Data columns in the CSV format are in the following order:

ServerId,AccountId,PlanBillingPeriodStart,PlanBillingPeriodEnd,BillingPeriodStart,BillingPeriodEnd,BillingPeriodMessageCount,BillingPeriodBandwidthCountInBytes,BillingPeriodBandwidthCountInGigabytes,BillingPeriodApiCount,ApiAllowance,MaxApiAllowance,MessageAllowance,MaxMessageAllowance,BandwidthAllowanceInBytes,MaxBandwidthAllowanceInBytes,BandwidthAllowanceInGigabytes,MaxBandwidthAllowanceInGigabytes,IsOverApiAllowance,IsOverBandwidthAllowance,IsOverMessageAllowance

Response Parameters

object.AccountId
The ID of the account that owns the server being queried.
object.ApiAllowance
The maximum number of Reporting API calls that can be made in a single billing period before overages occur. This is a soft limit and is based on the subscription plan for the server.
object.BandwidthAllowanceInBytes
The maximum amount of bandwidth (in bytes) that can be used for message injection in a single billing period before overages occur. This is a soft limit and is based on the subscription plan for the server.
object.BandwidthAllowanceInGigabytes
The maximum amount of bandwidth (in gigabytes) that can be used for message injection in a single billing period before overages occur. This is a soft limit and is based on the subscription plan for the server.
object.BillingPeriodApiCount
The number of calls to the Reporting API have been made in the current billing period.
object.BillingPeriodBandwidthCountInBytes
The amount of bandwidth (in bytes) used for message injection in the current billing period.
object.BillingPeriodBandwidthCountInGigabytes
The amount of bandwidth (in gigabytes) used for message injection in the current billing period.
object.BillingPeriodEnd
The date and time that the current monthly billing period will end. This period relates to the billing of monthly plans and the billing of overages for all plans.
object.BillingPeriodMessageCount
The number of messages injected in the current billing period.
object.BillingPeriodStart
The date and time that the current monthly billing period started. This period relates to the billing of monthly plans and the billing of overages for all plans.
object.IsOverApiAllowance
This is set to true if the Reporting API access allowance has been reached.
object.IsOverBandwidthAllowance
This is set to true if the bandwidth allowance (in bytes) has been reached.
object.IsOverMessageAllowance
This is set to true if the message injection allowance has been reached.
object.MaxApiAllowance
The maximum number of Reporting API calls that can be made in a single billing period. This is a hard limit and is based on both the subscription plan for the server and settings in the control panel.
object.MaxBandwidthAllowanceInBytes
The maximum amount of bandwidth (in bytes) that can be used in a single billing period. This is a hard limit and is based on both the subscription plan for the server and settings in the control panel.
object.MaxBandwidthAllowanceInGigabytes
The maximum amount of bandwidth (in gigabytes) that can be used in a single billing period. This is a hard limit and is based on both the subscription plan for the server and settings in the control panel.
object.MaxMessageAllowance
The maximum number of messages that can be injected in a single billing period. This is a hard limit and is based on both the subscription plan for the server and settings in the control panel.
object.MessageAllowance
The maximum number of messages that can be injected in a single billing period before overages occur. This is a soft limit and is based on the subscription plan for the server.
object.PlanBillingPeriodEnd
The date and time that the current billing period for the subscription will end. This period should be one month for monthly subscriptions and one year for yearly subscriptions.
object.PlanBillingPeriodStart
The date and time that the current billing period for the subscription started. This period should be one month for monthly subscriptions and one year for yearly subscriptions.
object.ServerId
The ID of the server being queried.
timestamp
The date and time of the API request.

Response Examples

Example Response (JSON):

{
    "timestamp": "1368647126591",
    "object": {
        "ServerId": 0000,
        "AccountId": 0000,
        "PlanBillingPeriodStart": "2010-04-17",
        "PlanBillingPeriodEnd": "2010-05-17",
        "BillingPeriodStart": "2010-04-17",
        "BillingPeriodEnd": "2010-05-17",
        "BillingPeriodMessageCount": 0,
        "BillingPeriodBandwidthCountInBytes": 0,
        "BillingPeriodBandwidthCountInGigabytes": 0,
        "BillingPeriodApiCount": 0,
        "ApiAllowance": 1000000,
        "MaxApiAllowance": 1000000,
        "MessageAllowance": 1000000,
        "MaxMessageAllowance": 1000000,
        "BandwidthAllowanceInBytes": 131072000000,
        "MaxBandwidthAllowanceInBytes": 131072000000,
        "BandwidthAllowanceInGigabytes": 122.0703125,
        "MaxBandwidthAllowanceInGigabytes": 122.0703125,
        "IsOverApiAllowance": false,
        "IsOverBandwidthAllowance": false,
        "IsOverMessageAllowance": false
    }
}

Example Response (XML):

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<response>
    <timestamp>2010-05-15T19:46:08.5880368Z</timestamp>
    <object>
        <ServerId>0000</ServerId>
        <AccountId>0000</AccountId>
        <PlanBillingPeriodStart>2010-04-17</PlanBillingPeriodStart>
        <PlanBillingPeriodEnd>2010-05-17</PlanBillingPeriodEnd>
        <BillingPeriodStart>2010-04-17</BillingPeriodStart>
        <BillingPeriodEnd>2010-05-17</BillingPeriodEnd>
        <BillingPeriodMessageCount>0</BillingPeriodMessageCount>
        <BillingPeriodBandwidthCountInBytes>0</BillingPeriodBandwidthCountInBytes>
        <BillingPeriodBandwidthCountInGigabytes>0</BillingPeriodBandwidthCountInGigabytes>
        <BillingPeriodApiCount>0</BillingPeriodApiCount>
        <ApiAllowance>1000000</ApiAllowance>
        <MaxApiAllowance>1000000</MaxApiAllowance>
        <MessageAllowance>1000000</MessageAllowance>
        <MaxMessageAllowance>1000000</MaxMessageAllowance>
        <BandwidthAllowanceInBytes>131072000000</BandwidthAllowanceInBytes>
        <MaxBandwidthAllowanceInBytes>131072000000</MaxBandwidthAllowanceInBytes>
        <BandwidthAllowanceInGigabytes>122.0703125</BandwidthAllowanceInGigabytes>
        <MaxBandwidthAllowanceInGigabytes>122.0703125</MaxBandwidthAllowanceInGigabytes>
        <IsOverApiAllowance>false</IsOverApiAllowance>
        <IsOverBandwidthAllowance>false</IsOverBandwidthAllowance>
        <IsOverMessageAllowance>false</IsOverMessageAllowance>
    </object>
</response>

Example Response (CSV):

ServerId,AccountId,PlanBillingPeriodStart,PlanBillingPeriodEnd,BillingPeriodStart,BillingPeriodEnd,BillingPeriodMessageCount,BillingPeriodBandwidthCountInBytes,BillingPeriodBandwidthCountInGigabytes,BillingPeriodApiCount,ApiAllowance,MaxApiAllowance,MessageAllowance,MaxMessageAllowance,BandwidthAllowanceInBytes,MaxBandwidthAllowanceInBytes,BandwidthAllowanceInGigabytes,MaxBandwidthAllowanceInGigabytes,IsOverApiAllowance,IsOverBandwidthAllowance,IsOverMessageAllowance
0000,0000,2010-04-17,2010-05-17,2010-04-17,2010-05-17,3,1430,0.0000013317912817001342773438,0,1000000,1000000,1000000,1000000,131072000000,131072000000,122.0703125,122.0703125,False,False,False

Customers Who Trust in SocketLabs

You’re in good company when working with SocketLabs. Here are some companies who have also trusted SocketLabs.

Why SocketLabs?

What Our Customers Are Saying!