search_conversionlab – ConversionLab Docs

Search ConversionLab projects, ideas, insights, experiments, metrics, pages, and audiences. Uses semantic search only when team AI is available, otherwise falls back to keyword search.

Permissions

{
  "ability": "mcp:read or mcp:write",
  "role": "Team membership and applicable entity view policies are required.",
  "plan": "The billing account must have the MCP entitlement. Writes also require a writable billing mode and applicable entity limits.",
  "team": "The bearer token selects exactly one Team. Other team_id values cannot change the tenant."
}

Input

{
  "properties": {
    "query": {
      "description": "Search query",
      "type": "string"
    },
    "project_id": {
      "description": "Optional project ID filter",
      "type": "integer"
    },
    "state": {
      "description": "Optional idea or experiment state name filter",
      "type": "string"
    },
    "metric_id": {
      "description": "Optional metric ID filter",
      "type": "integer"
    },
    "limit": {
      "description": "Result limit; defaults to 10 and is clamped to 1–10",
      "type": "integer"
    }
  },
  "type": "object",
  "required": [
    "query"
  ]
}

Output

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "keyword",
        "semantic"
      ]
    },
    "fallback_reason": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "empty_query",
        "ai_unavailable",
        "ai_rate_limited",
        "semantic_failed",
        null
      ]
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "project",
              "idea",
              "insight",
              "observation",
              "experiment",
              "metric",
              "page",
              "audience"
            ]
          },
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "score": {
            "type": [
              "number",
              "null"
            ]
          },
          "project_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "state": {
            "type": [
              "string",
              "null"
            ]
          },
          "section": {
            "type": "string"
          },
          "project": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "type",
          "id",
          "name",
          "content",
          "score",
          "project_id",
          "state"
        ]
      }
    }
  },
  "required": [
    "mode",
    "fallback_reason",
    "results"
  ]
}

Examples

Request arguments

{
  "query": "delivery",
  "project_id": 1,
  "limit": 5
}

Result

{
  "mode": "keyword",
  "fallback_reason": "ai_unavailable",
  "results": [
    {
      "type": "idea",
      "id": 101,
      "name": "Explain delivery times at checkout",
      "content": "State the delivery estimate before payment.",
      "score": null,
      "project_id": 1,
      "state": "Backlog"
    }
  ]
}

Errors

[
  {
    "status": 401,
    "description": "Missing, expired, or revoked bearer token."
  },
  {
    "status": 403,
    "description": "Missing MCP ability, team membership, plan entitlement, or user permission."
  },
  {
    "status": 404,
    "description": "The MCP server is disabled."
  },
  {
    "status": 429,
    "description": "Rate limited; honor Retry-After before retrying."
  },
  {
    "description": "Tool execution or validation failures are MCP error results. Inspect isError; a successful HTTP status alone does not indicate a successful tool call."
  }
]

An expired or revoked key cannot connect. A missing ability, role, feature entitlement, or team access prevents the operation. See authentication.