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 with the same access rules. Agents can also search and read the public PropertyDataLabs documentation and link to the page used in an answer.

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 JSON. Use the IDs returned by the API; job and run IDs differ from the IDs in web-app URLs.

List endpoints accept limit from 1 to 100, with a default of 25. 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.

REST endpoints

Paths below are relative to the REST base URL shown in Agent access. The OpenAPI document includes request and response fields.

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 response includes the latest successful run's credit usage when available, a new estimate, the available credit balance, and a warning that actual usage may differ. Importer and Aggregator estimates use a current Zillow listing count when available. If that lookup fails, the response labels the estimate as a fallback.

An approval token is returned only when the available balance covers the estimate. Otherwise, canStart is false and approvalToken is null: add credits and request a new estimate.

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 property response contains normalized identity, source URL, address, coordinates, listing status, price or rent, beds, baths, living area, lot area, measurement 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.

This is a smaller set of fields than a full Advanced Cloud export. It does not include raw source responses, owner names, or phone numbers.

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. The exported fields are the normalized fields listed above; these exports do not use your spreadsheet export template. Read and export operations do not consume Cloud collection credits.

Exports default to a maximum of 100,000 records. The service returns an error if the configured limit is exceeded. After an export expires, create another export from the retained run with a new idempotency key.

Public sanitized examples:

• JSON export sample
• NDJSON export sample

Tokens and reconnecting

Tokens created in the web app expire after 90 days. To replace one, create a new credential, update the client, confirm that it connects, and revoke the old credential. Scopes on an existing token cannot be changed; create a replacement when a client needs different permissions.

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.