Skip to main content
GHL MCP Guide
OPS

Opportunity Search

Pipelines & Opportunities · Intermediate · Updated March 2026

Search opportunities across pipelines using status, stage, contact, value range, and date filters. Essential for reporting and pipeline analysis.

A pipeline is only as useful as your ability to query it. Opportunity Search gives you filtered access to your deal data — find all open deals above a certain value, list everything in a specific stage, pull deals closing this month, or search by assigned team member. This is the foundation for building custom reporting, dashboards, and pipeline intelligence outside of GHL’s built-in views.

What This MCP Tool Does

Search and filter opportunities across all pipelines in a location. Returns paginated results matching your criteria, including deal values, stages, statuses, contact associations, and dates.

Endpoint Reference

Search opportunities: GET /opportunities/search Query opportunities with multiple filter parameters. Returns matching records with pagination support.

Authentication

Requires a Private Integration Token (PIT) with the opportunities scope enabled.

Key Parameters

  • pipelineId — filter by specific pipeline
  • pipelineStageId — filter by specific stage
  • status — open, won, lost, abandoned
  • contactId — find all opportunities for a specific contact
  • assignedTo — filter by deal owner
  • monetaryValue — filter by value range
  • date — filter by creation or expected close date
  • limit, offset — pagination controls
  • order — sort direction

Important Notes

Search results are paginated. Large pipelines with hundreds or thousands of deals require multiple calls to retrieve all results. Use the limit and offset parameters to page through data.

The search returns opportunity metadata but not the full communication history or related tasks. For complete deal context, retrieve the individual opportunity via Opportunity CRUD and the associated contact via Contact CRUD.

This endpoint is the basis for building custom pipeline reports. Pull deals by stage, aggregate values, calculate conversion rates between stages, and track pipeline velocity — all from MCP calls combined with your own analysis logic.

Common Questions

Can I search across all pipelines at once? Yes. Omit the pipelineId filter to search across every pipeline in the location.

Can I filter by monetary value range? Yes. Use value parameters to find deals above, below, or within a specific range.

How do I calculate pipeline value by stage? Search by pipeline, group results by stage ID, and sum the monetary values. This gives you a stage-by-stage pipeline snapshot.

Is there a way to get deal velocity (time in each stage)? Not directly. You’d need to track stage change timestamps and calculate duration. GHL stores stage change history, but accessing it may require the individual opportunity record.

Back to GHL MCP Guide