List listing alerts 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

mcp.json 
{
  "RealScout API MCP server": {
    "url": "https://bump.sh/realscout/doc/realscout-api/mcp"
  }
}
Close
GET /listing-alerts
Bearer auth

Listing alerts across the agent's contacts or for one contact, newest first, with type and email_settings (mode and schedule, with the settings of whichever mode it is in). An archived contact's alerts are left out, as in the agent app.

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

Query parameters

  • contact_id string

    Only this contact's alerts; omit for all of the agent's contacts. An id that is none of the agent's contacts is an empty page.

  • mode string

    Only alerts in this email_settings mode; omit for every mode.

    Values are automated, handpicked, or disabled.

  • cursor string

    Opaque cursor from the previous page's next_cursor; a cursor another list issued is refused.

  • limit integer

    Page size, 1 to 100.

    Minimum value is 1, maximum value is 100. Default value is 25.

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
    • data array[object] Required
      Hide data attributes Show data 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
    • has_more boolean Required
    • next_cursor string | null Required

      Send as cursor for the next page; null on the last one.
  • 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 
curl -H "Authorization: Bearer rs_agent_..." "https://www.realscout.com/api/agent/v1/listing-alerts?contact_id=VXNlci0xMjM="
Response examples (200) 
{
  "data": [
    {
      "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="
    },
    {
      "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"
    },
    {
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Response examples (400) 
{
  "error": {
    "code": "invalid_request",
    "message": "mode must be one of: automated, handpicked, disabled.",
    "field": "mode",
    "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 endpoint at GET /api/agent/v1/listing-alerts.",
    "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"
  }
}