Knowledge Base
Gryd API Usage Model
Overview
The Gryd API Usage Model explains how the API is used, which activity is free, which is billable, and how the pieces fit together.
Matching is free. You submit your data and Gryd matches it against its records at no charge, so you can explore coverage before you spend anything. Gryd bills when it delivers proprietary data: permit records, contractor details, licenses, contacts, system age, and jurisdiction data.
Paid endpoints are always billed, whether or not the area is covered. To help you decide, Gryd offers a free Coverage API that returns a ready-made coverage verdict and the measures behind it. Using it is optional, and you decide whether the answer changes your mind about making the paid call.
Every paid endpoint has its own price. A call to one endpoint does not cost the same as a call to another, because each returns different data with different value. Rates are set endpoint by endpoint. This article covers how the API is used and what is billable, not the rates themselves. For plan pricing, see Pricing. For an introduction to the API itself, see Intro to Gryd by BuildZoom API.
Key terminology
These six terms describe how software talks to the API. The API client runs in the customer's infrastructure, and Gryd's endpoints run in Gryd's. An API client sends a request and Gryd sends back a response. Only a request that Gryd completes successfully counts as a call, and whether that call is billed depends on the endpoint.
API terms

Product terms
What is billable
The flow below follows a customer from the lookup endpoints to a paid call.

Usage rules and billing logic
Gryd bills on calls. The rules are:
- Matching is free. Lookup endpoints and the Coverage API are never billed.
- Paid endpoints are always billed per call, whether or not the area is covered.
- Checking coverage first is the customer's choice. See How to Measure Coverage for how to use coverage information to fit your use case.
- Permit endpoints return up to 250 (TBC) permits per page. Each page is a separate call, billed separately.
- A paid call that returns no records is still a call, and it is billed.
- Error responses, whether server errors (5xx) or client errors (4xx), are not calls and are not billed.
- If a lookup endpoint finds no match, there is no paid call to make, so nothing is billed.
- Free APIs are rate limited. See Rate limits and usage restrictions below.
- All usage for all endpoints is tracked, whether free or billable. Each endpoint has a corresponding entitlement attached to it.
Data coverage
Gryd has data from all 50 states and covers more than 2,500 jurisdictions, made up of cities, counties and metropolitan areas. The database holds more than 400M building permits, 100M+ properties and 6.5M+ contractors. Historical coverage spans decades in many jurisdictions, with records dating back over 25 years. Coverage, available fields, and record detail vary by jurisdiction and source. For more on where the data comes from, see Data Sourcing & Methodology.
Coverage also has a narrower meaning in the API. It describes how complete Gryd's permit data is for a permit jurisdiction, and it is measured by comparing Gryd's permit counts with Census survey counts. The free Coverage API exposes the measures behind it, such as population, permits and new construction permits over the last 12 months, the Census ratio, months with new construction data, and active sources in the last 30 days. You decide whether coverage is good enough to make a paid call. Because paid calls are always billed, that decision matters.
A ready-made coverage verdict
The Coverage API is intended to return a ready-made coverage verdict alongside the raw measures, so most customers do not have to build a rule themselves. The interpretation behind the verdict comes from Gryd's analytics team, building on the status definitions in the new permit jurisdictions index. The verdict labels and the rules behind them are still to come from the analytics team. For now the verdict is returned only by the Coverage API, not by Property Search.
If you want more control, you can build your own rule from the measures. The verdict is information only and plays no part in billing.
What customers receive
Each endpoint does one job and returns a specific kind of data. Lookup endpoints and the Coverage API return matches and coverage information at no charge. Paid endpoints return proprietary data and are billed per call. Every paid endpoint is priced separately. For the fields available in Gryd data, see Data Fields & Schema. For other ways to receive data, see Data Products & Delivery.
Free: lookup endpoints and the Coverage API
Paid endpoints: property data
Paid endpoints: contractor data
Paid endpoints: jurisdiction data
Why the usage model works this way
Under the old model, Gryd decided what counted as covered, and the answer was a single yes or no. In the new model, Gryd gives you the measures and lets you decide. This is better for customers in four ways:
- The answer fits your use case. Coverage means different things to different customers. A roof-age underwriter needs recent, steady permit data. A new construction analyst needs completeness against the Census. One fixed flag could only serve one of them well. How to Measure Coverage includes examples.
- You can see why. The old flag was a single value with no explanation. The measures behind the new answer are visible, so you can check an area, explain a decision, and change your rule as your needs change.
- You can check for free before you spend. The lookup endpoints and the Coverage API cost nothing, so you can screen properties and skip paid calls where Gryd's data is too thin for your purpose.
- Pricing is simpler. A paid call is billed the same way whether or not the area is covered, so you do not have to work out how Gryd's coverage definition affects your invoice.
Billing is also simpler overall. Every successful call to a paid endpoint is billed, and coverage plays no part. The old billing models split usage into covered and not-covered buckets, with a separate rate available for the latter. That split goes away, and so does any question about whether Gryd's coverage definition should change what a customer pays.
What customers take on
With the ready-made verdict, most customers take on little extra work compared with the old flag: one free call to the Coverage API, and no rule to build. If you want more control, you can build a rule from the measures, and the coverage guide gives you a recipe.
The old billing allowed a separate rate for uncovered zip codes. Any customer on a reduced rate will now pay the standard rate for those calls unless they screen the properties out first.
Rate limits and usage restrictions
Every free API has a rate limit: a cap on how many requests an API client can send in a given period. The lookup endpoints and the Coverage API are all rate limited. Free does not mean unlimited. Specific thresholds are to be confirmed. For the service levels that apply to the API, see API SLA.
An API client that hits a rate limit receives an HTTP 429 response. That is an error response, so it is not a call and is not billed. The client can try again later.
Related documentation