> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forestreet.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get search criteria history
> Retrieve the history of search criteria iterations for a specific market.
## Overview
This endpoint retrieves the complete history of search criteria iterations that have been used for a specific market
discovery.
**Workflow Step**: This is part of Phase 3 (Company Review) of the [Market Research
Workflow](/api-reference/guides/platform-discovery#phase-3-company-review-optional).
## Usage
Use this endpoint to track the evolution of search criteria for a market, which is helpful for:
* **Iteration**: See how search criteria evolved over time
* **Documentation**: Maintain a complete history of search parameters
## Best Practices
**Iteration Process**: This endpoint is useful when you've refined your search criteria multiple times and want to
track the progression.
**Important**: This endpoint only works for markets that have completed the discovery process. Make sure discovery is
finished before calling this endpoint.
## OpenAPI
````yaml get /v2/discovery/{marketId}/search-criteria/history
openapi: 3.0.0
info:
title: Forestreet API
version: 1.0.0
description: API documentation for Forestreet API
servers:
- url: https://rest.forestreet.com
description: Forestreet API V2 server
security:
- apiKeyAuth: []
- bearerAuth: []
- sessionIdQuery: []
tags: []
paths:
/v2/discovery/{marketId}/search-criteria/history:
get:
tags:
- Discovery
summary: Get search criteria history
description: >-
Retrieve the history of search criteria iterations for a specific
market.
parameters:
- schema:
type: string
description: Unique identifier for the market study.
required: true
description: Unique identifier for the market study.
name: marketId
in: path
responses:
'200':
description: Search criteria history retrieved
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
properties: {}
data:
type: array
items:
type: object
properties:
userPrompt:
type: string
nullable: true
description: Prompt used to generate the search criteria.
marketName:
type: string
description: Name of the market associated with the study.
marketType:
type: string
nullable: true
enum:
- service
- product
description: >-
Type classification of the market, such as region or
category.
marketRole:
type: string
nullable: true
enum:
- manufacturer
- distributor
- serviceProvider
- service provider
- consultant
- provider
description: >
Try to limit the companies to ones that fit a
specific role in the market. Possible values are:
- `"manufacturer"` – physical product manufacturing,
e.g. a car manufacturer
- `"distributor"` – physical product distribution,
e.g. a car dealership
- `"service provider"` – contractor or provider of
pre-defined services, e.g. a car repair shop
- `"consultant"` – consultants or advisers not
themselves participating in the market, but offer
advice to those who do, e.g. a motor regulatory
consultant
This is a hint to the discovery process and does not
guarantee that all returned companies will fit this
role. If insufficient companies are found, the
search will be broadened to include other roles.
If not provided, the AI will attempt to infer the
role based on the market name, and assumes
`"manufacturer"` if the market is too broad.
> 💡 It is recommended to write your intended role
in the market name, which the AI will be able to
infer from. Supplying a `marketRole` incompatible
with the market name might degrade the output.
keywords:
type: object
nullable: true
properties:
features:
type: array
nullable: true
items:
type: string
description: Keywords related to the market's features.
user:
type: array
nullable: true
items:
type: string
description: >-
Keywords related to user preferences or
behavior.
synonyms:
type: array
nullable: true
items:
type: string
description: Alternative terms related to the market search.
irrelevant:
type: array
nullable: true
items:
type: string
description: >-
Terms identified as irrelevant for the search
criteria.
required:
- features
- user
- synonyms
- irrelevant
description: >-
Grouped keywords associated with the search
criteria.
seedDomains:
type: array
nullable: true
items:
type: string
description: List of company domains you already know (if any).
assertions:
nullable: true
description: >-
Assumptions made during the search criteria
generation process.
constraints:
nullable: true
description: >-
Constraints applied to the search criteria
generation process.
locations:
type: array
nullable: true
items:
type: object
properties:
country:
type: string
nullable: true
address:
type: array
nullable: true
items:
type: string
coordinates:
type: array
nullable: true
items:
type: number
minItems: 2
maxItems: 2
required:
- country
description: List of country relevant to the study.
marketId:
type: number
description: Unique identifier for the market study.
performSearch:
type: boolean
nullable: true
description: >-
Indicates whether the search criteria should be used
to perform a search.
jobId:
type: number
nullable: true
description: >-
Unique identifier for the job associated with the
market study.
count:
type: number
nullable: true
description: Number of results returned for the search criteria.
projectKind:
type: string
nullable: true
enum:
- first_pass
- second_pass
- manually_added
description: Type of project associated with the search criteria.
pipelineChoices:
type: object
properties:
skipDiscoveryReview:
type: boolean
default: false
description: Skip the discovery review step.
runReverseGeocoding:
type: boolean
default: true
description: Run reverse geocoding step.
runDunsMapper:
type: boolean
default: true
description: Run DUNS mapper step.
runPeople:
type: boolean
default: true
description: Run people step.
runNews:
type: boolean
default: true
description: Run news step.
runEsg:
type: boolean
default: true
description: Run ESG step.
runMomentumScore:
type: boolean
default: true
description: Run momentum score step.
runMarketRadar:
type: boolean
default: false
description: Run market radar step.
runTopicAnalysis:
type: boolean
default: true
description: Run topic analysis step.
runPhraseExplorer:
type: boolean
default: true
description: Run phrase explorer step.
runGenerateFeatureMap:
type: boolean
default: true
description: Run generate feature map step.
sendPublishEmail:
type: boolean
default: true
description: Run send publish email step.
description: Choices for the publish pipeline.
createdAt:
type: string
nullable: true
format: date-time
description: Timestamp indicating when the record was created.
required:
- userPrompt
- marketName
- marketRole
- keywords
- seedDomains
- locations
- marketId
- performSearch
- jobId
- count
- createdAt
description: >-
Search criteria history data. Fields from MongoDB will
be populated, while fields from MySQL fallback will be
null.
required:
- metadata
- data
examples:
option-1:
summary: Search Criteria History
description: >-
Example response showing search criteria history for a
market
value:
metadata: {}
data:
- marketId: 12345
marketName: AI Healthcare Transcription Services
userPrompt: >-
Find AI-powered transcription services that serve
enterprise healthcare customers
marketType: service
marketRole: serviceProvider
keywords:
features:
- AI transcription
- speech-to-text
- healthcare
user:
- healthcare
- enterprise
- hospitals
synonyms:
- transcription
- dictation
- voice-to-text
irrelevant:
- manual transcription
- human transcription
count: 50
locations:
- country: GB
address:
- 123 Healthcare St
- Suite 100
coordinates:
- 51.5074
- -0.1278
jobId: 12345
projectKind: first_pass
performSearch: true
createdAt: '2023-01-15T10:30:00Z'
- marketId: 12345
marketName: AI Transcription Services
userPrompt: Find AI transcription services
marketType: service
marketRole: serviceProvider
keywords:
features:
- AI transcription
- speech-to-text
user:
- enterprise
synonyms:
- transcription
- dictation
irrelevant:
- manual transcription
count: 25
locations:
- country: GB
address:
- 123 Healthcare St
- Suite 100
coordinates:
- 51.5074
- -0.1278
jobId: 12345
projectKind: second_pass
performSearch: false
createdAt: '2023-01-15T10:30:00Z'
option-2:
summary: Search Criteria History
description: >-
Example response showing search criteria history for a
market
value:
metadata: {}
data:
- marketId: 12345
marketName: AI Healthcare Transcription Services
userPrompt: null
marketType: null
marketRole: null
keywords: null
seedDomains: null
assertions: null
constraints: null
locations:
- country: GB
jobId: null
projectKind: first_pass
createdAt: '2023-01-15T10:30:00Z'
count: null
performSearch: null
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
INVALID_INPUT:
value:
success: false
errorCode: INVALID_INPUT
message: Bad Request
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
FORBIDDEN:
value:
success: false
errorCode: FORBIDDEN
message: Forbidden
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
NOT_FOUND:
value:
success: false
errorCode: NOT_FOUND
message: Not Found
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
INTERNAL_SERVER_ERROR:
value:
success: false
errorCode: INTERNAL_SERVER_ERROR
message: Internal Server Error
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Pass a static API key for every request, provided by your customer
support.
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer token authentication, using a sessionId generated by `GET
/v2/auth/session`.
sessionIdQuery:
type: apiKey
in: query
name: sessionId
description: >-
Session ID passed as a query parameter for authentication, provided by
`GET /v2/auth/session`.
````