Monitoring usage and spend

Did you know that as an API customer you can track your usage and billing in your Pipl account? The usage page shows your match rates. The billing page shows your previous invoices as well as your current spend, which is updated hourly. The current spend is displayed prior to applying any adjustments, refunds, or discounts.

You also can monitor your account proactively via code using the HTTP headers returned by the the Pipl API response

We recommend logging every API request, including search_ids, errors and warnings in order to improve your integration. These logs should be reviewed regularly.

Setting your API key quota

API keys do not have a specific quota when they are generated. Only a Pipl account administrator can set your API key quota.

To set a quota for the key you want to use:

  1. Go to your API keys page.
  2. Hover over the key you want to use to view the options menu for that key.
  3. Select ‘Set quota’ from the menu.
  4. The ‘Change Key Quota’ popup window will appear.
  5. Select the quota limit. The quota limit is the number of matches you want to allow for the quota period. Setting the quota to 0 will reset the quota.
  6. Select the quota period (hourly/daily/monthly).
  7. Press ‘Change’.
  8. The new quota you’ve set will show under the key.

API key quotas represent the number of matches for a given period of time. They allow you to set a budget per key and control your spend. We’ve provided an example below.

Key

Price per match

Quota limit

Quota period

Quota per invoice

Business Premium

$0.40

2000

Monthly

$800

Using the HTTP headers

The quota that you have set will be shown on every API response in the HTTP header as "X-APIKey-Quota-Alloted".

The date and time of the quota reset will show in the HTTP header as "X-Quota-Reset".

Every billable response—such as every match returned from the API—will be counted against the quota of the key used and will be shown in the HTTP header as "X-APIKey-Quota-Current".

Applying the example used in the table above, the headers will return as follows:
json
X-APIKey-Quota-Allotted 2000
X-Quota-Reset 2018-10-01 00:00:00 ##The end of the month##
X-APIKey-Quota-Current 1

Use the three headers to conduct as many calculations as you wish. For example: 
1. Calculate the number of queries you have left before your quota resets:
**Left queries** =  **X-APIKey-Quota-Alloted** - **X-APIKey-Quota-Current**
2. Calculate your current spend:
**Spend** = **Price-per-match*** x **X-APIKey-Quota-Current**
**Depending on the key you used*


[block:api-header]
{
  "title": "Example Python code"
}
[/block]

*The 'moneyed' and 'decimal' libraries are used to help handle the calculation and presentation.* 


[block:code]
{
  "codes": [
    {
      "code": "from piplapis.error import APIError\nfrom piplapis.search import SearchAPIRequest\nfrom piplapis.search import SearchAPIResponse\nfrom piplapis.data import Person\nfrom piplapis.data.fields import Address, Email, Name, Phone\nfrom moneyed import Money\nfrom decimal import *\n\nperson = Person()\nperson.emails.append(Email('[email protected]'))\nSearchAPIRequest.set_default_settings(api_key='YOUR_BUSINESS_PREMIUM_KEY_HERE')\nrequest = SearchAPIRequest(person=person)\nresponse = request.send()\n\nprint(\"This is your Quota for the key: \", response.quota_allotted)\nprint(\"This is your usage of the key: \", response.quota_current)\nprint(\"This is when the quota resets: \", response.quota_reset)\nusagePercent = Decimal(Decimal(response.quota_current)/Decimal(response.quota_allotted))  #the percent of the quota(matches) used so far\nkeyPrice = Decimal('0.40')                                                                #The cost per match for the key I'm using\ntotalUsage = Money(amount=(keyPrice*response.quota_current),currency='USD')               #The estimated total cost of the matches\nprint(\"You have used \", response.quota_current,\" of \",response.quota_allotted,\"queries.\")\nprint(\"You have used \",usagePercent,\"% of your monthly quota. To date your bill amounts to\",totalUsage)\n",
      "language": "python",
      "name": null
    }
  ]
}
[/block]