Back to Top

Account Stats

Overview

The Account Stats endpoint allows you to query FullContact to view your API account usage for the current month or a previous month that you can define using the optional period parameter.

Note: This endpoint is rate-limited to 30 calls per hour.

Requests

https://api.fullcontact.com/v2/stats.json?period=2012-08&apiKey=xxxx

Required Parameter
Optional Parameter
copy
https://api.fullcontact.com/v2/stats.json?period=2012-08&apiKey=xxxx
https://api.fullcontact.com/v2/stats.xml?period=2012-08&apiKey=xxxx

Parameters

Name Description
apiKey This API key is assigned to you by FullContact. It is used to identify and authorize your request. Your API key should be kept private, and should never be displayed publicly.
period(optional) You can define the month that you want to see usage stats for by using the period parameter. The format is YYYY-MM (period=2012-08).

Example Response

The API will respond in JSON or XML.

HTTP/1.1 200 OK
Date: Tue Sep 30 17:52:23 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
  "status": 200,
  "periodStart": "2012-11-01T00:00:00 -0600",
  "periodEnd": "2012-11-30T23:59:59 -0700",
  "plan": "Fictitious $99.00/mo with $0.03 overage",
  "planBasePrice": 99,
  "planOveragePrice": 0.03,
  "applicationId": "xxxxxxxxxxxxx",
  "metrics": 
  [
    {
      "metricName": "Success - Basic (\"200\")",
      "metricId": "200",
      "planLevel": 10000,
      "usage": 170,
      "remaining": 9830,
      "overage": 0
    },
    {
      "metricName": "Success - No Charge (\"200\")",
      "metricId": "200_free",
      "usage": 0
    },
    {
      "metricName": "Bad Request (\"400\")",
      "metricId": "400",
      "usage": 0
    },
    {
      "metricName": "Success - Enhanced (\"200\")",
      "metricId": "enhanced_200",
      "usage": 0
    },
    {
      "metricName": "Success - Card Reader (\"202\")",
      "metricId": "202_CardShark",
      "usage": 0
    },
    {
      "metricName": "Queued (\"202\")",
      "metricId": "202",
      "usage": 9
    },
    {
      "metricName": "Not Found (\"404\")",
      "metricId": "404",
      "usage": 36
    }
  ]
}
HTTP/1.1 200 OK
Date: Tue Sep 30 17:52:23 UTC 2014 
Content-Type: text/xml;charset=UTF-8
<response>
	<status>200</status>
	<periodStart>2012-11-01T00:00:00 -0600</periodStart>
	<periodEnd>2012-11-30T23:59:59 -0700</periodEnd>
	<plan>TS 2: $99.00/mo for 50K/mo + $0.008 overage</plan>
	<planBasePrice>99</planBasePrice>
	<planOveragePrice>0.0080</planOveragePrice>
	<applicationId>xxxxxxxxxxxxx</applicationId>
	<metrics>
		<metric>
			<metricName>Success - Basic ("200")</metricName>
			<metricId>200</metricId>
			<planLevel>10000</planLevel>
			<usage>170</usage>
			<remaining>9830</remaining>
			<overage>0</overage>
		</metric>
		<metric>
			<metricName>Success - No Charge ("200")</metricName>
			<metricId>200_free</metricId>
			<usage>0</usage>
		</metric>
		<metric>
			<metricName>Bad Request ("400")</metricName>
			<metricId>400</metricId>
			<usage>0</usage>
		</metric>
		<metric>
			<metricName>Success - Enhanced ("200")</metricName>
			<metricId>enhanced_200</metricId>
			<usage>0</usage>
		</metric>
		<metric>
			<metricName>Success - Card Reader ("202")</metricName>
			<metricId>202_CardShark</metricId>
			<usage>0</usage>
		</metric>
		<metric>
			<metricName>Queued ("202")</metricName>
			<metricId>202</metricId>
			<usage>9</usage>
		</metric>
		<metric>
			<metricName>Not Found ("404")</metricName>
			<metricId>404</metricId>
			<usage>36</usage>
		</metric>
	</metrics>
</response>

Response Schema

The following is a description of the Account Stats API response schema. It includes every possible field, collection, and value you can expect to receive. Note that certain fields and collections will only appear in the response when the data is available.

{
  "status": {"type":"number"},  // common status codes can be found in diagram below
  "periodStart": {"type":"string"},
  "periodEnd": {"type":"string"},
  "plan": {"type":"string"},
  "planBasePrice": {"type":"number"},
  "planOveragePrice": {"type":"number"},
  "applicationId": {"type":"string"},
  "metrics": 
  [
    {
      "metricName": {"type":"string"},  // usage metrics can be found by logging into your account portal
      "metricId": {"type":"string"},
      "planLevel": {"type":"number"},
      "usage": {"type":"number"},
      "remaining": {"type":"number"},
      "overage": {"type":"number"}
    }
  ]
}

Stats API Diagram

Last modified: July 15 2013 08:42:09