Get listing alert | RealScout API documentation

Get listing alert Run in API Explorer

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://bump.sh/realscout/doc/realscout-api/mcp

Standard setup for AI tools providing an mcp.json file

{
  "RealScout API MCP server": {
    "url": "https://bump.sh/realscout/doc/realscout-api/mcp"
  }
}

GET /listing-alerts/{id}

Bearer auth

One listing alert: who it is for, its type, its email_settings (mode and schedule, with the settings of whichever mode it is in), its criteria as the sentence the agent app shows, and how many of its results sit in each of the agent app's tabs (unsent, sent, trashed).

Requires the listing_alerts:read scope. Rate budget: 300 calls per 1 minute per credential (the read class).

Path parameters

id string Required

The listing alert id.

Responses

200 application/json

OK
Hide headers attributes Show headers attributes
- X-RateLimit-Limit integer
  
  Calls allowed in the current window.
- X-RateLimit-Remaining integer
  
  Calls left in the current window.
- X-RateLimit-Reset integer
  
  Epoch seconds at which the window resets.
Hide response attributes Show response attributes object
- id string Required
- name string | null Required
- contact object | null Required
  
  Hide contact attributes Show contact attributes object | null
  
  id string Required
  
  realscout_url string(uri) Required
- search_type string | null Required
  
  Values are BASIC, EXCLUSIVES, ADVANCED, AI, or null.
- email_settings object Required
  
  Hide email_settings attributes Show email_settings attributes object
  
  mode string Required
  
  Values are automated, handpicked, or disabled.
  
  schedule string Required
  
  Values are ASAP, DAILY, WEEKLY, MONTHLY, or DISABLED.
  
  automated_settings object | null Required
  
  Hide automated_settings attributes Show automated_settings attributes object | null
  
  day_schedule array[string] | null Required
  
  next_send_at string(date-time) | null Required
  
  send_to_agent boolean Required
  
  send_oh_reminder boolean Required
  
  handpicked_settings object | null Required
  
  Hide handpicked_settings attributes Show handpicked_settings attributes object | null
  
  needs_review boolean Required
  
  last_reviewed_at string(date-time) | null Required
- last_ran_at string(date-time) | null Required
- sunset boolean | null Required
- source string | null Required
- created_at string(date-time) | null Required
- updated_at string(date-time) | null Required
- realscout_url string(uri) | null Required
- description string | null Required
- criteria_summary string | null Required
- results object | null Required
  
  Hide results attributes Show results attributes object | null
  
  unsent integer Required
  
  sent integer Required
  
  trashed integer Required
400 application/json

The request is invalid; field names the offending input when there is one. A body that is not valid JSON is refused before the API runs, as a bare 400 with no body.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
401 application/json

Invalid or missing bearer token.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
403 application/json

The credential was not granted the scope this call requires.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
404 application/json

Not found, or not yours: the two are indistinguishable on purpose.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
429 application/json

Rate limit exceeded; Retry-After says when to try again.
Hide headers attribute Show headers attribute
- Retry-After integer
  
  Seconds until the budget refills.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.
500 application/json

Something went wrong on our side.
Hide response attribute Show response attribute object
- error object Required
  
  Hide error attributes Show error attributes object
  
  code string Required
  
  Values are internal_error, invalid_request, missing_scope, not_found, rate_limited, or unauthorized.
  
  message string Required
  
  field string
  
  The offending input, when one input is to blame.
  
  request_id string Required
  
  Quote this when reporting a problem; it identifies the call in our logs.

GET /listing-alerts/{id}

curl -H "Authorization: Bearer rs_agent_..." https://www.realscout.com/api/agent/v1/listing-alerts/U2F2ZWRTZWFyY2gtOTk=

Response examples (200)

{
  "id": "U2F2ZWRTZWFyY2gtOTk=",
  "name": "Sunnyvale 3BR",
  "contact": {
    "id": "VXNlci0xMjM=",
    "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM="
  },
  "search_type": "BASIC",
  "email_settings": {
    "mode": "automated",
    "schedule": "DAILY",
    "automated_settings": {
      "day_schedule": [
        "0_AM",
        "1_AM",
        "2_AM",
        "3_AM",
        "4_AM",
        "5_AM",
        "6_AM"
      ],
      "next_send_at": "2026-09-02T03:00:00Z",
      "send_to_agent": false,
      "send_oh_reminder": true
    },
    "handpicked_settings": null
  },
  "last_ran_at": "2026-08-18T13:00:00Z",
  "sunset": false,
  "source": null,
  "created_at": "2026-08-01T17:00:00Z",
  "updated_at": "2026-08-18T13:00:00Z",
  "realscout_url": "https://danaagent.realscout.com/agent/listing-alerts/U2F2ZWRTZWFyY2gtOTk=",
  "description": "Basic Search",
  "criteria_summary": "Status contains any: For Sale AND Price: 500,000 to 900,000 AND Bedrooms: 3+",
  "results": {
    "unsent": 12,
    "sent": 48,
    "trashed": 3
  }
}

{
  "id": "U2F2ZWRTZWFyY2gtMTAw",
  "name": "Palo Alto picks",
  "contact": {
    "id": "VXNlci0xMjM=",
    "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM="
  },
  "search_type": "BASIC",
  "email_settings": {
    "mode": "handpicked",
    "schedule": "DAILY",
    "automated_settings": null,
    "handpicked_settings": {
      "needs_review": true,
      "last_reviewed_at": "2026-08-17T16:00:00Z"
    }
  },
  "last_ran_at": "2026-08-18T13:00:00Z",
  "sunset": false,
  "source": null,
  "created_at": "2026-08-01T17:00:00Z",
  "updated_at": "2026-08-18T13:00:00Z",
  "realscout_url": "https://danaagent.realscout.com/agent/listing-alerts/U2F2ZWRTZWFyY2gtMTAw",
  "description": "Basic Search",
  "criteria_summary": "Status contains any: For Sale AND Price: 500,000 to 900,000 AND Bedrooms: 3+",
  "results": {
    "unsent": 12,
    "sent": 48,
    "trashed": 3
  }
}

{
  "id": "U2F2ZWRTZWFyY2gtMTAx",
  "name": "Old Mountain View search",
  "contact": {
    "id": "VXNlci0xMjM=",
    "realscout_url": "https://www.realscout.com/agent/contacts/VXNlci0xMjM="
  },
  "search_type": "BASIC",
  "email_settings": {
    "mode": "disabled",
    "schedule": "DISABLED",
    "automated_settings": null,
    "handpicked_settings": null
  },
  "last_ran_at": "2026-08-18T13:00:00Z",
  "sunset": true,
  "source": null,
  "created_at": "2026-08-01T17:00:00Z",
  "updated_at": "2026-08-18T13:00:00Z",
  "realscout_url": "https://danaagent.realscout.com/agent/listing-alerts/U2F2ZWRTZWFyY2gtMTAx",
  "description": "Basic Search",
  "criteria_summary": "Status contains any: For Sale AND Price: 500,000 to 900,000 AND Bedrooms: 3+",
  "results": {
    "unsent": 12,
    "sent": 48,
    "trashed": 3
  }
}

Response examples (400)

{
  "error": {
    "code": "invalid_request",
    "message": "unknown is not a field this endpoint takes.",
    "field": "unknown",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (401)

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing credentials.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (403)

{
  "error": {
    "code": "missing_scope",
    "message": "This call requires the listing_alerts:read scope, which this credential was not granted.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (404)

{
  "error": {
    "code": "not_found",
    "message": "No listing alert with id U2F2ZWRTZWFyY2gtOTk= for this agent.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (429)

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}

Response examples (500)

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "9b2f4c1e-7d3a-4e5b-8f6c-0a1d2e3f4b5c"
  }
}