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

# Execute a search on a saved search

> Search opportunities using a saved search query

## Request

<ParamField path="id" type="string" required>
  ID of the saved search to execute
</ParamField>

<ParamField query="per" type="integer" default={50}>
  Number of results per page (max: 100)
</ParamField>

<ParamField query="page" type="integer" default={1}>
  Page number for pagination
</ParamField>

<ParamField query="sort" type="string">
  Which date field to use for sorting. Must be one of: 'relevance', 'posted\_at', 'modified\_at' or 'respond\_by'. Default: falls back to saved search date range parameter
</ParamField>

<ParamField query="sort_direction" type="string" default="desc">
  Sort direction for results ('asc' or 'desc', default: falls back to saved search sort direction)
</ParamField>

<ParamField query="start_date" type="string">
  Start date for filtering results (ISO 8601 format, default: 1 day ago)
</ParamField>

<ParamField query="end_date" type="string">
  End date for filtering results (ISO 8601 format, default: current date)
</ParamField>

<ParamField query="date_range_param" type="string">
  Which date field to use for date range filtering. Must be one of: 'posted\_at', 'modified\_at', or 'respond\_by'. Default: falls back to saved search date range parameter
</ParamField>

## Response

<ResponseField name="results" type="array">
  Array of opportunity objects matching the search criteria

  <Expandable title="Opportunity Properties">
    <ResponseField name="id" type="string">
      Unique identifier for the opportunity
    </ResponseField>

    <ResponseField name="title" type="string">
      Original title from the solicitation
    </ResponseField>

    <ResponseField name="uniqueKey" type="string">
      Unique identifier key for the opportunity
    </ResponseField>

    <ResponseField name="externalIdentifier" type="string">
      External reference number (e.g., solicitation number)
    </ResponseField>

    <ResponseField name="url" type="string">
      Govly web URL for viewing the opportunity
    </ResponseField>

    <ResponseField name="apiUrl" type="string">
      Direct API URL for retrieving this opportunity
    </ResponseField>

    <ResponseField name="externalUrl" type="string">
      URL to the original government source
    </ResponseField>

    <ResponseField name="postedAt" type="string">
      ISO 8601 timestamp of when the opportunity was posted
    </ResponseField>

    <ResponseField name="modifiedAt" type="string">
      ISO 8601 timestamp of the last modification
    </ResponseField>

    <ResponseField name="respondBy" type="string">
      ISO 8601 timestamp of the response deadline
    </ResponseField>

    <ResponseField name="questionDeadline" type="string">
      ISO 8601 timestamp of the deadline for submitting questions about the opportunity. Returns null when not available from the source data.
    </ResponseField>

    <ResponseField name="lastSummarizedAt" type="string">
      ISO 8601 timestamp of when the opportunity was last processed by AI
    </ResponseField>

    <ResponseField name="recordType" type="string">
      Type of record (e.g., "solicitation", "forecast", "award")
    </ResponseField>

    <ResponseField name="jurisdiction" type="string">
      Jurisdiction name (e.g., "United States", "California")
    </ResponseField>

    <ResponseField name="isoCode" type="string">
      Jurisdiction ISO code (e.g., "US", "US-CA")
    </ResponseField>

    <ResponseField name="contractVehicle" type="string">
      Contract vehicle being used for the opportunity
    </ResponseField>

    <ResponseField name="naics" type="string[]">
      NAICS (North American Industry Classification System) codes for the opportunity. Only the most specific codes are returned (e.g., 6-digit codes are preferred over sector-level codes). Empty array if none.
    </ResponseField>

    <ResponseField name="aiTitle" type="string">
      AI-generated descriptive title
    </ResponseField>

    <ResponseField name="aiSummary" type="string">
      AI-generated summary of the opportunity
    </ResponseField>

    <ResponseField name="aiShortSummary" type="string">
      AI-generated short summary (3-6 sentences) that is concise and to the point while preserving key details like OEMs, products, quantities, and part numbers
    </ResponseField>

    <ResponseField name="aiEstimatedValueMin" type="float">
      Minimum estimated value of the opportunity in USD
    </ResponseField>

    <ResponseField name="aiEstimatedValueMax" type="float">
      Maximum estimated value of the opportunity in USD
    </ResponseField>

    <ResponseField name="aiPeriodOfPerformance" type="string">
      Description of the performance period for the opportunity
    </ResponseField>

    <ResponseField name="aiLineItems" type="object">
      Structured breakdown of products and services mentioned in the opportunity

      <Expandable title="Properties">
        <ResponseField name="products" type="array">
          Array of product line items

          <Expandable title="Product Properties">
            <ResponseField name="vendor" type="string">Name of the product vendor</ResponseField>
            <ResponseField name="product" type="string">Product name</ResponseField>
            <ResponseField name="quantity" type="number">Quantity requested</ResponseField>
            <ResponseField name="description" type="string">Product description</ResponseField>
            <ResponseField name="partNumber" type="string">Product part number</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="services" type="array">
          Array of service line items

          <Expandable title="Service Properties">
            <ResponseField name="vendor" type="string">Name of the service provider</ResponseField>
            <ResponseField name="service" type="string">Service name</ResponseField>
            <ResponseField name="quantity" type="number">Quantity of services</ResponseField>
            <ResponseField name="description" type="string">Service description</ResponseField>
            <ResponseField name="partNumber" type="string">Service part number</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="aiRawProducts" type="string[]">
      Array of primary product names mentioned in the opportunity
    </ResponseField>

    <ResponseField name="aiRawVendors" type="object[]">
      Array of primary vendor information

      <Expandable title="Properties">
        <ResponseField name="name" type="string">Vendor name</ResponseField>
        <ResponseField name="website" type="string">Vendor website URL</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="aiRawCompetingProducts" type="string[]">
      Array of competing product names identified in the opportunity
    </ResponseField>

    <ResponseField name="aiRawCompetingVendors" type="object[]">
      Array of competing vendor information

      <Expandable title="Properties">
        <ResponseField name="name" type="string">Vendor name</ResponseField>
        <ResponseField name="website" type="string">Vendor website URL</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="description" type="string">
      Full opportunity description from the latest source
    </ResponseField>

    <ResponseField name="latestModificationReason" type="string">
      Reason for the most recent modification
    </ResponseField>

    <ResponseField name="productCategoryTags" type="string[]">
      Product category tags associated with the opportunity
    </ResponseField>

    <ResponseField name="majorEndItem" type="string">
      Major end item from the data source context
    </ResponseField>

    <ResponseField name="warningTags" type="string[]">
      Warning labels for the opportunity. Possible values: `"Brand Name or Equal"`, `"Clearance Likely Required"`, `"Clearance Possibly Required"`. Empty array if none.
    </ResponseField>

    <ResponseField name="contactName" type="string">
      Primary contact name
    </ResponseField>

    <ResponseField name="contactEmail" type="string">
      Primary contact email address
    </ResponseField>

    <ResponseField name="contactPhoneNumber" type="string">
      Primary contact phone number
    </ResponseField>

    <ResponseField name="address" type="string">
      Primary location address
    </ResponseField>

    <ResponseField name="buyer" type="object">
      Information about the buying organization

      <Expandable title="Properties">
        <ResponseField name="id" type="string">Buyer organization ID</ResponseField>
        <ResponseField name="name" type="string">Name of the buying organization</ResponseField>
        <ResponseField name="hierarchy" type="string[]">Array of organization names from highest to lowest level</ResponseField>
        <ResponseField name="hierarchyIds" type="string[]">Array of organization IDs corresponding to the hierarchy</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="attachments" type="object[]">
      Array of documents attached to the opportunity

      <Expandable title="Properties">
        <ResponseField name="checksum" type="string">SHA-256 checksum of the file</ResponseField>
        <ResponseField name="filename" type="string">Original filename</ResponseField>
        <ResponseField name="url" type="string">Secure URL to download the attachment</ResponseField>
        <ResponseField name="cuiLikely" type="boolean">Whether the attachment likely contains Controlled Unclassified Information (CUI)</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="sources" type="object[]">
      Array of source records for this opportunity

      <Expandable title="Properties">
        <ResponseField name="id" type="string">Unique identifier for the source</ResponseField>
        <ResponseField name="noticeType" type="string">Type of notice (e.g., "presolicitation", "solicitation", "award")</ResponseField>
        <ResponseField name="recordType" type="string">Type of record</ResponseField>
        <ResponseField name="digest" type="string">Unique digest for the source content</ResponseField>
        <ResponseField name="externalUrl" type="string">URL to the original source</ResponseField>
        <ResponseField name="createdAt" type="string">ISO 8601 timestamp when the source was created in Govly</ResponseField>
        <ResponseField name="postedAt" type="string">ISO 8601 timestamp when the source was posted</ResponseField>
        <ResponseField name="noBidAt" type="string">ISO 8601 timestamp if a no-bid decision was recorded</ResponseField>
        <ResponseField name="hasJustification" type="boolean">Whether the source includes a justification document</ResponseField>
        <ResponseField name="hasEvent" type="boolean">Whether the source is associated with an event</ResponseField>
        <ResponseField name="modificationReason" type="string">Reason for the modification if this is an amendment</ResponseField>
        <ResponseField name="attachmentChecksums" type="string[]">Array of checksums for attachments associated with this source</ResponseField>
        <ResponseField name="rawEmail" type="string">URL to the raw email if this source came from email (only visible to source owner)</ResponseField>
        <ResponseField name="providerContext" type="object">Provider-specific context data (only visible to source owner)</ResponseField>

        <ResponseField name="dataSourceContext" type="object">
          Additional context from the data source

          <Expandable title="Properties">
            <ResponseField name="emailMessageChecksum" type="string">Checksum of the email message if applicable</ResponseField>
            <ResponseField name="rawNoticeType" type="string">Original notice type from the source</ResponseField>
            <ResponseField name="rawSetAside" type="string">Set-aside information from the source</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="highlights" type="object">
      Object containing highlighted text snippets from fields that matched the saved search criteria

      <Expandable title="Properties">
        <ResponseField name="[field_name]" type="string[]">
          Array of text snippets from the field containing highlighted matches. The field name will be the name of the field that contained matches (e.g., 'title', 'description', etc.)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Pagination metadata

  <Expandable title="Properties">
    <ResponseField name="currentPage" type="integer">
      Current page number
    </ResponseField>

    <ResponseField name="per" type="integer">
      Number of items per page
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of items
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages
    </ResponseField>
  </Expandable>
</ResponseField>
