AI agent access

AI agent access lets a client inspect property data that your account has already collected, manage existing Cloud jobs, and request approval before starting a credit-consuming run. It supports a remote Model Context Protocol (MCP) endpoint and a versioned REST API backed by the same permissions and response schemas. Agents can also search and read the public PropertyDataLabs documentation to answer product questions with a canonical source link.

Access is included with Solo Lifetime, Pro, Ultra, and eligible legacy Team or Enterprise accounts. Solo Lifetime does not include Cloud credits, and Agent API or MCP access does not bypass the credit check for a job run. Agents cannot create or delete Cloud jobs. Deletion remains exclusively available in the PropertyDataLabs UI.

For client-specific setup instructions, start with Get started with MCP.

Before you connect

1. Open Settings → Agent access.
2. Confirm that the account shows Access enabled.
3. Create a credential with only the scopes your client needs.
4. Copy the token when it appears. PropertyDataLabs never shows the complete token again.

Treat the token like a password. Do not put it in a prompt, source repository, screenshot, or support message. Create a different token for each client so you can revoke one connection without affecting the others.

Connect an MCP client

The Agent access page shows the MCP endpoint for the current environment. Configure a remote Streamable HTTP server with that URL and send the personal access token as a bearer credential.

{
  "url": "<MCP URL shown in Agent access>",
  "headers": {
    "Authorization": "Bearer pdl_pat_..."
  }
}

Client configuration formats differ. Keep the token in the client's secret or environment-variable store when one is available.

Use the REST API

The Agent access page also shows the REST base URL. Its OpenAPI document is available at <REST base URL>/openapi.json.

curl --fail-with-body \
  --header "Authorization: Bearer $PDL_AGENT_TOKEN" \
  "${PDL_AGENT_API_URL}/jobs?limit=25"

Responses use normal JSON and opaque cursors. Pass pagination.nextCursor as the next request's cursor; do not inspect, modify, store permanently, or share a cursor between credentials. Cursors expire and are bound to the credential, operation, and request filters.

Available access scopes

The service defaults to 120 requests per minute for each credential and 300 requests per minute for each user. Responses include agent-specific limit, remaining, and reset headers. A 429 response includes Retry-After; wait for that interval rather than retrying immediately.

Tool annotations help a client present actions, but the server enforces scopes and ownership on every request. Revoked, expired, or insufficiently scoped credentials are rejected.

Documentation search is intentionally outside the resource scopes because it reads only public content. Every valid credential can use pdl_search_docs and pdl_read_doc. REST clients can use GET /docs/search and GET /docs/content. Search results return both the canonical user-facing URL and its machine-readable Markdown twin; answers should cite the canonical URL.

Changing an automatic schedule requires both jobs:write and jobs:run, because enabling a schedule can spend credits later. Restoring an archived job that already has an automatic schedule also requires both scopes. Archive and unarchive actions are reversible. No Agent API or MCP scope grants deletion. Job responses include automaticSchedule so a client can confirm the current setting after reading or editing a job.

Approval before a run

The client must prepare a run estimate before it can start a job. The estimate response contains the latest successful run's actual credit usage when available, a fresh estimate, the current credit balance, an uncertainty warning, and a short-lived approval token. For Zillow search jobs, the estimate service uses the existing scraping-provider path to obtain a current listing count when needed. If that lookup fails, the response identifies the estimate as a fallback instead of presenting it as live data.

The client must display approvalMessage and wait for an explicit yes. It may then submit the unchanged approval token with approved: true and a new idempotency key. Tokens expire after 10 minutes and stop working if the job changes. Actual credit usage can differ because listings and building units can change.

REST uses POST /jobs/{jobId}/run-estimate to prepare the prompt and POST /job-runs to start the approved run. MCP uses pdl_prepare_job_run and pdl_start_job_run.

What an agent can read

The initial property contract contains normalized identity, source URL, address, coordinates, listing status, price or rent, beds, baths, living area, lot area, units, observation time, and collection time. Missing values are returned as explicit null values. Dates use ISO 8601 and numeric measurements remain numbers.

PropertyDataLabs reports information retained from the configured collection source. It is not an MLS, appraisal, title report, underwriting decision, legal opinion, or guarantee that a listing is current. Check the source URL and observation time before relying on a record.

The Agent API does not expose raw provider payloads, owner names, phone numbers, or other fields that require a separate privacy and redistribution review.

Use exports for larger result sets

Page through properties for interactive investigation. For a large result, create an ndjson export and poll its export ID until the status is ready. Download URLs are short-lived and can be renewed while the export artifact remains available. Artifacts expire 24 hours after creation.

Each export includes a manifest with source IDs, schema version, listing type, scraping depth, selected fields, record count, MIME type, checksum, file size, and expiry. Read and export operations do not consume Cloud collection credits in this release.

Public sanitized examples:

• JSON export sample
• NDJSON export sample

Errors and support

REST errors include a stable code and request ID. MCP tool errors include the same safe message in the tool result. Save the request ID when contacting support, but never include your token, signed download URL, property payload, or personal information.

Check the service status page for known incidents. For an integration problem, contact support with the client name, approximate time, operation, and request ID.