Guides

Credits

Suggest Edits

Parcl Labs uses a simple credit-based consumption model for its API. Read below to learn more about how credits work and how to manage them effectively.


What are Credits?

Credits are the unit of measure for consuming data through the Parcl Labs API. Each credit represents one datapoint retrieved from the API.

Here's how credits work:

  • For housing metrics, 1 credit = 1 date of data, regardless of whether you're pulling a daily, weekly, or monthly aggregate metric.
  • For property data, 1 credit = 1 property returned in your results

Why use Credits?

Credits give you control over the data you consume and therefore the amount of credits you need. We're committed to offering the best developer experience - that extends to how you use and pay for our API.

Key benefits of the credit system:

  • Flexibility: Whether you need full market history or real-time updates across multiple locations, our credit system lets you pull exactly what you need for your use case. No overpaying for unused data.
  • Simplified API interaction: We eliminate arbitrary limits and pagination, making API calls fast and straightforward. This simplicity lets you focus more on what matters - building your applications.

How to Manage Credits

Use Parameters to Control Credit Usage

Use API parameters to control exactly how many datapoints - and therefore credits - you retrieve with each request. Each endpoint has parameters that let you specify exactly what data you need.

Key parameters for managing credit consumption:

  • start_date and end_date: Control the time range of data retrieved
  • limit: Specify the maximum number of results returned

Remember: Each datapoint retrieved equals one credit, so these parameters directly control your credit usage.


Track Credit Usage in API Responses

Every API response includes real-time credit data in the account object, showing both credits used and remaining:

  • est_credits_used: Shows credits consumed by your current request
  • est_remaining_credits: Shows your remaining credits after the request

For example:

{
  "account": {
    "est_credits_used": 3,
    "est_remaining_credits": 997
  },

Monitor Credits in Your Dashboard

In addition to the API response data, you can also monitor your credit usage in real-time through the API dashboard. Usage analytics update continuously, showing your current credit balance and consumption patterns.


Add More Credits at Any Time

We provide the best value in housing data.

Our basic plan includes 1,000 free credits monthly, which reset at the start of each 30-day cycle.

Need more? Upgrade anytime through the API dashboard. Paid plans offer more flexibility. For example, with credit rollover, you can bank and accumulate unused credits over time - they're always there when you need them.


How Credits Work for Housing Metrics

For housing metrics, 1 credit = 1 date of data returned, regardless of whether you're pulling daily, weekly, or monthly metrics.

Every housing metric endpoint is clearly labeled with its frequency (monthly, weekly, or daily), making it easy to calculate your credit usage based on your date range.

Here's what pulling one year of data costs:

  • Monthly metrics: 12 credits (1 datapoint per month)
  • Weekly metrics: 52 credits (1 datapoint per week)
  • Daily metrics: 365 credits (1 datapoint per day)

Use the limit parameter to directly control how many datapoints are returned and credits are used.


Housing Metrics: Example Credit Calculation

Here's how credits are calculated in practice. Each datapoint in the response equals one credit used - whether you're pulling a single date or multiple dates of data:

Single datapoint = 1 credit:

{
  "parcl_id": "5314518",
  "property_type": "SINGLE_FAMILY",
  "items": [
    {
      "date": "2024-05-20",
      "for_sale_inventory": 87
    }
  ],
  "total": 90,
  "limit": 1,
  "offset": 0
}

3 datapoints = 3 credits:

{
  "parcl_id": "5314518",
  "property_type": "SINGLE_FAMILY",
  "items": [
    {
      "date": "2024-05-20",
      "for_sale_inventory": 87
    },
    {
      "date": "2024-05-13",
      "for_sale_inventory": 86
    },
    {
      "date": "2024-05-06",
      "for_sale_inventory": 82
    }
  ],
  "total": 90,
  "limit": 3,
  "offset": 0
}

Note: The Search Market endpoint is free and doesn't count against your credits. We want you to easily find the markets you need to kickstart your analysis without impacting your available credits.


How Credits Work for Property Data

For property data, 1 credit = 1 property returned. Here's how credits work for each property endpoint:

  • Property Search: Returns all matching properties in a market – the number of properties returned = credits used
  • Address Search: One credit per address searched and successfully matched
  • Property Event History: One credit per property's history requested

Example credit usage:

  • Address Search with 100 addresses: 100 credits (1 credit per address)
  • Property Event History for 100 properties: 100 credits (1 credit per property)

Address Search and Property Event History are POST endpoints where credits correspond 1:1 with the number of properties (parcl_property_id) requested.


Property Search Credit Tips 

Property Search works differently than Address Search and Event History when it comes to credit management. With Address Search and Event History, you specify exactly which properties you want - so you know upfront how many credits you'll use. With Property Search, you define search criteria and get all matching properties in a market.

This design enables high performance and complete results (you'll get ALL properties matching your criteria), but requires careful management of your queries.

To control credit usage effectively, test your queries with narrow criteria before expanding scope:

  • Start with specific search parameters
  • Use smaller geographic areas (zip codes instead of metro areas)

Once you understand your property and credit needs, you can scale up and optimize accordingly.


Get Help With Credits

Questions about credits or need help optimizing your usage? Join our developer community. The forum is actively monitored by our engineering team, so you'll get expert help quickly.

Updated 9 days ago

What’s Next