> ## Documentation Index > Fetch the complete documentation index at: https://docs.shovels.ai/llms.txt > Use this file to discover all available pages before exploring further. # Quick Answers > Fast answers to the most common Shovels questions about API limits, data coverage, pricing, permit data, contractors, and more. Fast, concise answers to the most frequently asked questions about Shovels. *** ## Pricing & Plans ### How much does Shovels cost? Shovels Online and API pricing starts with a free tier. View current plans at [shovels.ai/pricing](https://www.shovels.ai/pricing). Enterprise Data License (EDL) pricing requires contacting [sales@shovels.ai](mailto:sales@shovels.ai). ### Is there a free trial? Yes. Shovels Online free trials include access to the last 12 months of data. The API free trial includes 250 requests with access to the full historical dataset. ### How do I cancel my subscription? Log in at [app.shovels.ai/account](https://app.shovels.ai/account) → **Manage subscription** → Cancel in the Stripe billing portal. Access continues until the end of the billing period. See [How to cancel](/docs/knowledge-base/shovels-online/cancel-subscription). ### What is Shovels' refund policy? Refunds are reviewed case-by-case for charges within the last 30 days. Email [support@shovels.ai](mailto:support@shovels.ai) with your account email and charge details. See [Refund Policy](/docs/knowledge-base/company/refund-policy). ### What can I do with Shovels data? Internal business use: research, prospecting, lead generation, and product integration. You cannot upload it to ad platforms (Facebook, Google, etc.), resell, or redistribute it. See [Data usage terms](/docs/knowledge-base/company/data-usage-terms). ### What's the difference between API and EDL? **API**: Best for lookups, integrations, and local lead lists. **EDL**: Best for bulk data analysis. Full dataset delivered to your data warehouse. *** ## API Basics ### What is my API limit? The free trial includes **250 requests** (each API call = 1 request, regardless of records returned). Paid plans use a credit system with custom credit limits where each record returned counts against your credits. Contact [sales@shovels.ai](mailto:sales@shovels.ai) for details. ### How many records per API call? Search endpoints return up to 100 records per page (default: 10). Detail endpoints accept up to 50 IDs per call. ### How do API credits work? Each record returned counts against your credits. A search returning 100 permits uses 100 credits; a single permit lookup uses 1 credit. ### Where do I find my API key? Log in at [app.shovels.ai/account](https://app.shovels.ai/account?tab=apikey) and find it on the **API key** tab. ### What does a 422 error mean? A required parameter is missing. Most commonly, you need to resolve an address to a geo\_id first using the Address Search endpoint. *** ## CLI (Command Line) ### How do I install the CLI? Run the install script: `curl -LsSf https://shovels.ai/install.sh | sh`. The script downloads the correct binary for your platform and installs it to `~/.shovels/bin`. Add to PATH if needed. ### How do I configure my API key? Two options: (1) Environment variable: `export SHOVELS_API_KEY=your-key`, or (2) Config file (persistent): `shovels config set api-key your-key`. Verify with `shovels config show`. ### What's the difference between CLI and API? The CLI wraps the Shovels REST API but handles authentication headers, cursor pagination, rate-limit retries, and credit tracking automatically. Use the CLI from terminals, shell scripts, or AI agents. Use the API directly for application integrations. ### How do I get all results instead of just 50? Use `--limit all`. The CLI automatically handles pagination and fetches up to 10,000 records by default (configurable with `--max-records`). ### What commands are available? Main commands: `permits search`, `permits get`, `properties search`, `properties get`, `contractors search`, `contractors get`, `contractors permits`, `contractors employees`, `contractors metrics`, `decisions search`, `decisions get`, `addresses search`, `cities search`, `tags list`, `schema`, `usage`, `config`. Run `shovels --help` for full list. ### How do I query properties from the CLI? Use `shovels properties search` (added in v0.8.0). It needs `--geo-id`, `--legal-owner`, or both — not both a geo and a date range like `permits search`. Example: `shovels properties search --geo-id 92024 --permit-tags "-solar" --limit 10`. See [Querying properties from the CLI](/docs/knowledge-base/cli/properties). ### How do I find properties with no permit of a given type in the CLI? Prefix the tag with `-` inside `--permit-tags`: `--permit-tags "-solar"`. Combine presence and absence in one value, e.g. `--permit-tags "roofing,-solar"`. Every absence row carries a `trust` object. See [Absence searches and trust fields](/docs/knowledge-base/cli/absence-and-trust). ### Why does my properties result have several trust\_summaries? Because each entry covers one API page. `--limit 205` fetches three pages, so you get three summaries. The CLI deliberately doesn't merge them — each rate is row-weighted over its own page, so averaging them would be wrong. Read the worst page instead: `jq '[.meta.trust_summaries[].expected_miss_rate] | max'`. ### Why is there no --permit-to on properties search? A property record keeps only the latest permit date per work type, so a closed date window can't be answered correctly. Only "ever" and "since date D" (`--permit-from`) are expressible. Use `shovels permits search` for date windows. ### How do I search one owner's properties nationwide? `shovels properties search --legal-owner "INVITATION HOMES"` — no `--geo-id` needed. Repeat the flag for up to 10 owners; values are never split on commas, so `"SMITH, JOHN"` stays one owner. ### Why did properties get fail when only one ID was bad? An ID that's well-formed but unknown is fine — it's omitted and listed in `meta.missing` with exit `0`. But an ID that can't be decoded as an address ID, or a city/county/jurisdiction geo\_id, fails the whole request with exit `1`. Validate before batching 50. ### How do I see a command's response fields without spending credits? `shovels schema properties search` prints every field with its type, unit, and description, plus a jq-ready `field_index`. It runs offline and needs no API key. `--dry-run` similarly prints the resolved HTTP request without calling the API. ### Can I use the CLI with scripts and AI agents? Yes. The CLI outputs JSON to stdout and errors to stderr with meaningful exit codes (0=success, 1=client error, 2=auth error, 3=rate limited, 4=credits exhausted, 5=server error). Perfect for piping to `jq` or scripting. ### What does exit code 2 mean? Exit code 2 is an authentication error—your API key is missing or invalid. Set it with `shovels config set api-key YOUR_KEY` or via the `SHOVELS_API_KEY` environment variable. *** ## Data Coverage ### What areas does Shovels cover? Approximately 2,000 jurisdictions covering about 85% of the US population. ### How far back does the data go? At least 2010 for all jurisdictions. Many jurisdictions have data going back further. ### How often is data updated? Monthly. We add 5-10 million new records and 1-5 million status updates each month. ### Why am I getting so few results? Common causes: limited jurisdiction coverage, filters too narrow, recent permits not yet indexed (1–2 month lag), or limited digitization in the local jurisdiction. See [Why am I getting so few results?](/docs/knowledge-base/data/quality/few-results). ### Where does Shovels get its data? Directly from jurisdictions through relationships with local governments, online permitting portals, and public records requests. We don't purchase data from other vendors. *** ## Permits ### What is a geo\_id? A unique geographic identifier that can represent a state (`CA`), zip code (`94103`), city, county, or specific address. Use the Address Search API to get a geo\_id. ### What are the permit statuses? * **in\_review**: Application submitted, awaiting approval * **active**: Approved, work can proceed * **final**: Completed, passed inspection * **inactive**: Stalled, expired, or abandoned ### Why do some permits have no address? New construction permits are often filed before official addresses exist. These permits have state and jurisdiction info but no address ID. ### What's the difference between permit ID and permit number? **Permit ID**: Globally unique identifier generated by Shovels. **Permit number**: Assigned by the jurisdiction—may duplicate across different cities. *** ## Properties ### What is the Properties API? Two beta endpoints covering roughly 159 million US properties. Each record is one property with its permit history summarized on it: permit counts, work-type tags, latest activity dates, contractors, job values, and property attributes. See [How to search for properties](/docs/knowledge-base/api/properties/property-search). ### How do I find properties with no permit of a given type? Prefix the tag with `-` in `permit_tags` (e.g. `permit_tags=-solar`). Every absence answer carries trust fields—including the page-level `expected_miss_rate`—that tell you how confident the "no permit on record" claim is. See [Absence search](/docs/knowledge-base/api/properties/absence-queries). ### Can I search properties by a date window or "before" a date? No. A property record keeps only the latest permit date per work type, so only "ever" and "since date D" queries are supported. For date windows or upper bounds, use [Search Permits](/api-reference/permits/search-permits). See [Properties vs Permits](/docs/knowledge-base/api/properties/properties-vs-permits). ### Can I search properties by owner? Yes—`legal_owner` is the one filter that works nationwide with no location. Pass up to 10 owner names to get their properties across the US. ### Can I search properties by parcel number (APN)? No. APN is returned on every record for mapping into your own systems, but it's not searchable: APNs are county-specific, millions collide across counties, and about 30% of properties have none. ### Can I search properties by jurisdiction? No. Jurisdiction is recorded on only a minority of property records, so scoping to it would silently drop properties that were never permitted. Jurisdiction geo\_ids are rejected — scope by city, county, state, ZIP, or address instead. ### Why do my property attribute filters return nothing? Attribute data (value, size, year, units, type) covers roughly 60-70% of properties, and a property with no value for an attribute never matches a range filter on it. Stacking several filters can empty a result that returns plenty of rows without them. Loosen or drop one filter at a time. ### Can I query properties from the CLI? Yes, as of CLI v0.8.0: `shovels properties search` and `shovels properties get`. See [Querying properties from the CLI](/docs/knowledge-base/cli/properties). *** ## Decisions ### What are Shovels Decisions? Structured records of municipal zoning and land use decisions from city councils and planning boards across the US. Decisions give you earlier visibility into development activity—often months before permits are filed. ### What types of decisions does Shovels track? Four primary categories: **Spot Rezoning** (changes to specific properties), **Area Rezoning** (broader geographic changes), **Zoning Code Modifications** (changes to the rules themselves), and **Special Use Permits** (conditional approvals for specific activities). ### How do Decisions relate to permits? Decisions precede permits in the development lifecycle. A rezoning approval or special use permit typically comes weeks to months before the developer applies for building permits. ### How early can I see projects with Decisions? Depends on project complexity: 2-4 weeks for minor commercial renovations, 1-3 months for new homes, 3-6 months for multifamily, and 6-12 months for large commercial projects. ### What information is in a decision record? Property location and coordinates, zoning changes (previous and new), involved parties (applicant, owner, developer, representative), project value and lot size, allowed uses, a "why it matters" summary, and a link to the source meeting record. ### Which plans include Decisions? All of them. Decisions are included in the API free trial and in every paid plan at no additional charge. Decisions are currently in beta. ### How do I query Decisions in the API? Use the [Search Decisions](/docs/knowledge-base/api/decisions/searching-decisions) endpoint. It requires a date range (`decision_from`, `decision_to`) and a `geo_id`. To fetch specific records, use [Get Decisions By ID](/docs/knowledge-base/api/decisions/decisions-by-id) with up to 50 IDs. ### What's the Decisions coverage? At launch, Decisions covered 600+ cities and nearly 200,000 records—about half the jurisdictions where Shovels has permit coverage—and continues to expand. See the [Coverage Dashboard](https://www.shovels.ai/coverage). *** ## Contractors ### How is contractor data organized? Each contractor has a unique contractor ID (deduplicated within each state). Related contractors share a group ID linking them to parent organizations. ### What contact information is available? Business name, address, phone numbers (primary and all known), email addresses, license numbers, and employee data (via API endpoint). ### Are contractors deduplicated across states? No. The same contractor operating in multiple states has separate IDs per state. National deduplication is in development. *** ## Shovels Online ### What can I do with the free trial? Search permits and contractors, use filters, and explore the last 12 months of data. CSV downloads require a paid plan. ### What is Charlie? Charlie is the AI agent inside Shovels Online, opened with the **Agent** button. Ask permit data questions in plain English instead of building a search with filters. Included on every plan, with usage limits that scale with your plan. See [What is Charlie?](/docs/knowledge-base/shovels-online/charlie). ### How does search work? Searches use AND logic—results match ALL selected criteria. You can search by geography, date range, permit type, keywords, and more. *** ## Enterprise (EDL) ### What formats are available? Parquet (preferred), CSV, or JSON. Typical delivery size is 15-20 GB. ### Where can data be delivered? Snowflake, BigQuery, Databricks, or as downloadable files. ### How do I track new records in monthly deliveries? Use the `first_seen_date` field. Records with `first_seen_date` after your last delivery are new. *** ## Contact ### How do I contact Shovels? * **Support**: [support@shovels.ai](mailto:support@shovels.ai) * **Sales**: [sales@shovels.ai](mailto:sales@shovels.ai) * **Phone**: 1-800-511-7457 * **Address**: 3515 Mt. Diablo Blvd, Unit #51, Lafayette, CA 94549 *** ## Related Resources * [Full Glossary](/docs/knowledge-base/glossary) - Detailed term definitions * [API Reference](/api-reference) - Complete API documentation * [Data Dictionary](https://www.shovels.ai/data-dictionary) - Field definitions