> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List pitches

> List the pitches the API key can reach, as the app's Pitches tab does: 7-day trial projects run for prospects, on each workspace's shared pitch prompt allowance. Every pitch is listed whatever its status, converted ones included, in the tab's four views (`view`). Each pitch carries its status, expiry and `daysLeft`, whether its one 7-day extension is used, its manual refreshes, whether it is hidden from the project picker, its tracked prompt count, and whether it can be reactivated (`canReactivate`) or extended (`canExtend`, only in its last 48 hours) right now. A converted pitch is a regular project now and carries only its id, name, domain, workspace and `convertedAt`. `workspaces` holds, for each workspace where you can create pitches or read one, whether its plan has pitches, whether your role and plan allow creating them there, and its pitch allowance. A workspace with API access disabled is left out, and a project-scoped key sees only its pitch. Pitch ids work with every project endpoint.



## OpenAPI

````yaml /api-reference/openapi.json get /api/mcp/pitches
openapi: 3.1.0
info:
  title: Searchable REST API
  version: 1.0.0
  summary: >-
    Query AI visibility, sources, sentiment, traffic, and content data, and
    trigger audits/reports/sitemap syncs.
  description: >-
    The Searchable REST API (`/api/mcp/*` and
    `/api/v1/projects/{projectId}/audits`) exposes the same data and actions
    available in the Searchable dashboard and MCP server, over plain HTTP with a
    bearer API key. It is a **read-mostly** surface — 75 of its 91 operations
    are GET. The mutating ones are capability-gated (a bare `write` scope does
    not satisfy a capability such as `prompt:draft`), and those listed under
    [Idempotency](/api-reference/introduction#idempotency) support
    `Idempotency-Key` replay.


    See **[Getting started](/api-reference/introduction)** for auth, rate
    limits, idempotency, and pagination conventions, and the **[error
    reference](/api/errors)** for every error `code` this API returns.


    `/api/mcp/*` is a frozen v1 contract — see the [changelog](/changelog) for
    the deprecation policy.
  contact:
    name: Searchable Support
    email: support@searchable.com
    url: https://docs.searchable.com/api-reference/introduction
servers:
  - url: https://app.searchable.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: List and inspect the projects an API key can reach.
  - name: Visibility
    description: >-
      AI visibility score, platform/topic/prompt/location breakdowns, and
      historical trend.
  - name: Share of Voice
    description: Brand vs. competitor mention-share ranking and its daily trend.
  - name: Competitors
    description: >-
      The project's tracked competitor roster — share of voice, sentiment, and
      mention/citation counts.
  - name: Sources
    description: >-
      Domains and URLs cited by AI answers — citation share, trend, and cached
      page content.
  - name: Sentiment
    description: Brand sentiment summary, trend, and head-to-head competitor comparison.
  - name: Query Fanout
    description: The sub-queries AI models generate when answering tracked prompts.
  - name: Traffic
    description: >-
      First-party AI-crawler and AI-referral traffic sourced from the
      tracker/CDN pipeline.
  - name: Shopping
    description: AI shopping/product-carousel visibility.
  - name: Ads
    description: >-
      Sponsored ads surfaced in AI answers — advertisers, individual creatives,
      ad-heavy prompts, and the frequency trend.
  - name: Answers
    description: Raw, per-response AI-answer data for a single prompt.
  - name: GSC
    description: Live Google Search Console performance data for the project's linked site.
  - name: GA4
    description: Live Google Analytics 4 traffic and AI-referral data.
  - name: Audits & Issues
    description: >-
      Page audits (technical + AEO), site issues, monitored pages, and sitemap
      sync.
  - name: Reports
    description: Generate and list shareable visibility/sentiment reports.
  - name: Articles
    description: Content pieces (articles) created in Searchable.
  - name: Opportunities
    description: >-
      Actionable, prioritized suggestions Searchable has surfaced for the
      project.
  - name: Brand
    description: Brand profile (knowledge base + AI-observed facts) and domain authority.
  - name: Prompts
    description: >-
      The project's prompt catalog (tracked, untracked, and AI-suggested
      prompts).
paths:
  /api/mcp/pitches:
    get:
      tags:
        - Projects
      summary: List pitches
      description: >-
        List the pitches the API key can reach, as the app's Pitches tab does:
        7-day trial projects run for prospects, on each workspace's shared pitch
        prompt allowance. Every pitch is listed whatever its status, converted
        ones included, in the tab's four views (`view`). Each pitch carries its
        status, expiry and `daysLeft`, whether its one 7-day extension is used,
        its manual refreshes, whether it is hidden from the project picker, its
        tracked prompt count, and whether it can be reactivated
        (`canReactivate`) or extended (`canExtend`, only in its last 48 hours)
        right now. A converted pitch is a regular project now and carries only
        its id, name, domain, workspace and `convertedAt`. `workspaces` holds,
        for each workspace where you can create pitches or read one, whether its
        plan has pitches, whether your role and plan allow creating them there,
        and its pitch allowance. A workspace with API access disabled is left
        out, and a project-scoped key sees only its pitch. Pitch ids work with
        every project endpoint.
      operationId: listPitches
      parameters:
        - name: workspaceId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: >-
            Only this workspace's pitches and allowance; an id from `GET
            /api/mcp/workspaces`.
        - name: view
          in: query
          required: false
          schema:
            type: string
            enum:
              - open
              - closed
              - converted
              - all
            default: all
          description: >-
            The Pitches tab's view: `open` (active), `closed` (declined or
            expired, shown as paused), `converted` (now client projects), or
            `all`.
      responses:
        '200':
          description: A list of pitches.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PitchListResponse'
        '400':
          $ref: '#/components/responses/defaultError'
        '401':
          $ref: '#/components/responses/defaultError'
        '403':
          $ref: '#/components/responses/defaultError'
        '429':
          $ref: '#/components/responses/rateLimited'
        '500':
          $ref: '#/components/responses/defaultError'
components:
  headers:
    XRequestId:
      description: This request's id. Include it when contacting support.
      schema:
        type: string
        format: uuid
    RateLimit:
      description: >-
        IETF draft rate-limit header:
        `"default";r=<remaining>;t=<seconds-until-reset>`. Omitted on responses
        where the limiter did not run (e.g. a pre-auth validation error, or a
        degraded limiter failing open).
      schema:
        type: string
    RateLimitPolicy:
      description: >-
        IETF draft rate-limit policy: `"default";q=<quota>;w=<window-seconds>`.
        Currently `q=600;w=60`.
      schema:
        type: string
    XRateLimitLimit:
      description: Requests allowed per window (600/minute per key).
      schema:
        type: integer
    XRateLimitRemaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
    XRateLimitReset:
      description: Absolute Unix-epoch second the current window resets.
      schema:
        type: integer
    RetryAfter:
      description: >-
        Seconds to wait before retrying. Set on 429s issued by Searchable's own
        rate limiter and on `409 idempotency_in_flight`; may be absent when an
        upstream provider (e.g. Google) rate-limits.
      schema:
        type: integer
  schemas:
    PitchListResponse:
      type: object
      properties:
        count:
          type: integer
          description: The number of pitches in `pitches`.
        pitches:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/PitchRecord'
              - $ref: '#/components/schemas/ConvertedPitchRecord'
        workspaces:
          type: array
          description: >-
            The pitch allowance of each workspace where you can create pitches
            or read one.
          items:
            $ref: '#/components/schemas/PitchWorkspaceAllowance'
      required:
        - count
        - pitches
        - workspaces
    PitchRecord:
      type: object
      description: >-
        One pitch as the Pitches tab shows it, worked out by the app's own
        rules. A converted pitch is a `ConvertedPitchRecord` instead.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        domain:
          type: string
        workspaceId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - active
            - declined
            - expired
          description: >-
            A declined pitch is paused; an expired one ran out of days. Both can
            be reactivated while `canReactivate` is true.
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        daysLeft:
          type:
            - integer
            - 'null'
          description: >-
            Whole days left, rounded up and never below zero; null without an
            expiry.
        extended:
          type: boolean
          description: Whether the pitch's one 7-day extension is used.
        refreshes:
          type: object
          description: The pitch's manual refreshes.
          properties:
            limit:
              type: integer
            used:
              type: integer
            remaining:
              type: integer
          required:
            - limit
            - used
            - remaining
        hiddenFromPicker:
          type: boolean
          description: Whether the pitch is hidden from the project picker.
        trackedPromptCount:
          type: integer
          description: Its tracked prompt-locations, as the pitch allowance counts them.
        canReactivate:
          type: boolean
          description: >-
            Whether a closed pitch can be brought back right now, as the app
            offers Reactivate.
        canExtend:
          type: boolean
          description: >-
            Whether the pitch can be extended right now: active, not yet
            extended, and in its last 48 hours.
      required:
        - id
        - name
        - domain
        - workspaceId
        - status
        - createdAt
        - expiresAt
        - daysLeft
        - extended
        - refreshes
        - hiddenFromPicker
        - trackedPromptCount
        - canReactivate
        - canExtend
    ConvertedPitchRecord:
      type: object
      description: >-
        A pitch that was converted into a client. It is a regular project now,
        so it carries no refreshes, allowance or actions; every project endpoint
        takes its id.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        domain:
          type: string
        workspaceId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - converted
        convertedAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - name
        - domain
        - workspaceId
        - status
        - convertedAt
    PitchWorkspaceAllowance:
      type: object
      description: >-
        A workspace's pitch standing: whether its plan has pitches, whether your
        role allows creating them, and its pitch prompt allowance.
      properties:
        workspaceId:
          type: string
          format: uuid
        workspaceName:
          type: string
        pitchesAvailable:
          type: boolean
          description: Whether the workspace's plan has pitches.
        canCreatePitches:
          type: boolean
          description: >-
            Whether your role and the workspace's plan allow creating pitches
            there. A key bound to a project, or one without the
            `project:provision` capability, still cannot create them.
        allowance:
          type: object
          description: >-
            The workspace's pitch prompt allowance, shared by its active
            pitches: tracked prompt-locations used, the limit, and what remains.
          properties:
            used:
              type: integer
            limit:
              type: integer
            remaining:
              type: integer
          required:
            - used
            - limit
            - remaining
      required:
        - workspaceId
        - workspaceName
        - pitchesAvailable
        - canCreatePitches
        - allowance
    Problem:
      type: object
      description: >-
        RFC 9457 `application/problem+json` error body. `error` is retained
        verbatim as a legacy compat key equal to `message`. Some codes carry
        additional fields beyond the base shape (documented per-code in the
        [error reference](/api/errors)) — always additive, never replacing
        these.
      properties:
        type:
          type: string
          format: uri
          description: >-
            A URL identifying the error kind — the error reference page,
            anchored to `code`.
        title:
          type: string
          description: Human-readable summary of `code`.
        status:
          type: integer
          description: The HTTP status code (matches the response status).
        code:
          type: string
          description: >-
            Machine-readable, stable error code — safe to branch on. See the
            [error reference](/api/errors) for the full catalog.
          enum:
            - unauthorized
            - forbidden
            - missing_scope
            - plan_upgrade_required
            - security_policy_denied
            - not_found
            - invalid_argument
            - invalid_country
            - no_domain
            - no_workspace
            - no_pages
            - bulk_limit_exceeded
            - quota_exceeded
            - project_not_runnable
            - pitch_not_supported
            - duplicate_domain
            - conflict
            - pitch_allowance_used
            - already_extended
            - cannot_reactivate
            - pitch_not_active
            - pitch_still_active
            - no_refreshes_left
            - refresh_failed
            - already_converted
            - extend_not_available_yet
            - not_a_pitch
            - preview_stale
            - confirmation_mismatch
            - destination_not_permitted
            - cross_reseller_transfer_not_allowed
            - same_workspace
            - destination_owner_missing
            - project_state_unsupported
            - creator_domain_conflict
            - source_domain_conflict
            - access_removal_not_confirmed
            - storage_object_missing
            - quota_projects_exceeded
            - quota_prompts_exceeded
            - in_flight_agent_runs
            - lock_timeout
            - serialization_failure
            - not_active
            - role_not_permitted
            - staff_not_in_tenant
            - staff_not_eligible
            - rate_limited
            - idempotency_in_flight
            - idempotency_conflict
            - query_timeout
            - gsc_not_connected
            - gsc_site_not_linked
            - gsc_access_denied
            - ga4_not_connected
            - traffic_not_connected
            - invalid_scope
            - host_outside_domain
            - invalid_citation_type
            - missing_competitor
            - unknown_competitor
            - duplicate_scope
            - rule_limit
            - internal_error
        error:
          type: string
          description: Legacy compat key. Always equal to `message`.
        message:
          type: string
          description: Human-readable error message (identical to `error`).
        howToFix:
          type: string
          description: Present on actionable errors — a concrete next step.
        requestId:
          type: string
          format: uuid
          description: This request's id. Include it when contacting support.
        requiresUpgrade:
          type: boolean
          description: Present on `plan_upgrade_required` (403).
        retryable:
          type: boolean
          description: >-
            Present on `rate_limited`, `idempotency_in_flight`, and
            `query_timeout`.
        timeout:
          type: boolean
          description: Present on `query_timeout` (504).
        quotaExceeded:
          type: boolean
          description: Present on `quota_exceeded` (403).
        current:
          type: integer
          description: Present on `quota_exceeded` — current usage.
        limit:
          type: integer
          description: Present on `quota_exceeded` — the plan's limit.
        bulkLimitExceeded:
          type: boolean
          description: Present on `bulk_limit_exceeded` (400, `POST /audits`).
        requested:
          type: integer
          description: >-
            Present on `bulk_limit_exceeded` / `quota_exceeded` — the count
            requested.
        maxAllowed:
          type: integer
          description: Present on `bulk_limit_exceeded` — the plan's per-request cap.
        details:
          description: >-
            Present on some `invalid_argument` (400) responses — a Zod
            `.flatten()` validation breakdown.
          type: object
          properties:
            formErrors:
              type: array
              items:
                type: string
            fieldErrors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
        opensAt:
          type: string
          format: date-time
          description: Present on `extend_not_available_yet` (409) — when extending opens.
        existing:
          type: object
          description: >-
            Present on `duplicate_domain` (409) from `POST /api/mcp/pitches` —
            the project or pitch that already holds the domain: `projectId`,
            `name`, `domain`, `workspaceId`, `workspaceName`, `isPitch`,
            `pitchStatus`, `isActive` and `canReactivate`. Absent when the
            holder sits in a workspace the API may not reach.
          additionalProperties: true
        quotaConflict:
          type: object
          description: >-
            Present on `quota_exceeded` (403) when converting a pitch would take
            the workspace past its plan's prompt allowance: the tracked
            prompt-locations in use (`current`), those the pitch adds
            (`pitchPromptCount`), the plan's `limit`, and the `shortfall`.
          properties:
            current:
              type: number
              description: 'Can be fractional: a weekly prompt-location counts as 1/7.'
            pitchPromptCount:
              type: integer
            limit:
              type: integer
            shortfall:
              type: number
              description: Can be fractional, as `current` can.
          required:
            - current
            - pitchPromptCount
            - limit
            - shortfall
      required:
        - type
        - title
        - status
        - code
        - error
        - message
  responses:
    defaultError:
      description: >-
        Error response. `code` is the machine-readable reason — see the [error
        reference](/api/errors) for the full catalog and remediation per code.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    rateLimited:
      description: >-
        Rate limited. Usually the per-API-key REST limit (600 requests/minute);
        on Google-backed endpoints it can also relay an upstream Google rate
        limit. `Retry-After` (seconds) is present when the limit was applied by
        Searchable's own rate limiter; it may be absent when an upstream
        provider rate-limits.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sea_xxxxx
      description: >-
        A Searchable API key, created under **Manage Account → Integrations →
        API Keys**. Send as `Authorization: Bearer sea_xxxxx`. Every key carries
        one or more scopes (`read`, `write`, `admin`) and may optionally be
        bound to a single project — see [Getting
        started](/api-reference/introduction#authentication).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.