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

JSON

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

XML

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

Parameters

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 Responses

The API will respond in JSON or XML.

JSON

{
  "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
    }
  ]
}

XML

<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

Stats Flow Diagram