Guides

Credits

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.

Example 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 100 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 V2: Returns all matching properties in a market. The number of properties returned = credits used
Address Search: One credit per address searched and successfully matched

Example credit usage:

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

Property Search Credit Tips

Property Search works differently than Address Search when it comes to credit usage. With Address Search, you specify exact properties upfront - so you know your credit cost. With Property Search, you define search criteria and get all matching properties, making credit usage variable based on how many properties match your criteria.

You can control this using the limit parameter to set an explicit cap on the number of properties returned (and therefore credits consumed).

This design delivers high performance and complete results (you get ALL properties matching your criteria), but requires careful query management.

Test your queries with narrow criteria before expanding scope:

Start specific: Use targeted search parameters
Start small: Use zip codes instead of metro areas
Scale: Once you understand the results, expand your criteria

Get Help With Credits

Questions about credits or need help optimizing your usage? Contact us at team@parcllabs.com.