> ## Documentation Index > Fetch the complete documentation index at: https://docs.shareofmodel.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Analysis > Create a Search analysis in the workspace: brand, website, engines, country and language, and the prompts, each naming its thematic, its topic and the persona of the workspace library asking it. The first collection starts right away and the workspace is debited one search credit per prompt. 402 when the workspace has fewer search credits than prompts; 422 when an engine is not in the references for this organization or when a persona id is unknown. Returns the analysis as GET /analyses/{project_id} does. Restricted to editors and above. ## OpenAPI ````yaml https://openapi.shareofmodel.ai/swagger-sos.json post /v1/organizations/{organization_id}/workspaces/{workspace_id}/search/analyses openapi: 3.0.3 info: title: Share Of Model API version: v1 description: >- ## Search The Share of Search API provides visibility, presence, and ranking metrics for tracked search and AI engine sources. Use it to analyse how a project performs across keywords, thematics, competitors, and ranked URLs over time. For the previous version of the API, see the [v1 documentation](https://api.shareofsearch.jplus.io/docs/v1). servers: - description: Search - Production API url: https://api.shareofsearch.jplus.io/ security: [] tags: - name: Projects description: >- Manage analyses (projects) within a workspace. Create new analyses and list existing ones. - name: Collects description: >- Access data collection runs and their raw results. List collect runs for an analysis, or retrieve the raw data captured during each run: domain rankings, brand mentions, keyword insights, and LLM/SERP responses. - name: Overview Metrics description: >- High-level, aggregated metrics that summarise the overall performance of an analysis. Use these endpoints to get a quick picture of visibility, presence, andranking across all keywords and sources. - name: Metrics description: >- Detailed, per-entity metrics for deep-diving into specific aspects of an analysis. Break down performance by domain, brand, keyword, URL, or competitor. - name: Insights description: >- Cross-project KPIs aggregated at the workspace or organization level. These endpoints consolidate metrics from all active projects within a workspace, or across every workspace of an organization, to provide a unified view of visibility, mentions, citations, sentiment, and ranking. - name: Shopping description: >- Shopping-specific metrics for analyses that track product listings in shopping engines. Measure product visibility, pricing, merchant coverage, and share of shelf across all tracked keywords and sources. - name: Ads description: >- Sponsored-ad performance across tracked prompts and engines, including coverage, advertiser diversity, brand presence, and share of ad voice. - name: Creators description: >- YouTube creators cited as sources in AI-engine search results, enriched with channel metrics and an Influence Score. Browse creators across every project in a workspace, narrowed by country, engine, brand, category, analysis, and persona filters. - name: Video Analyses description: >- On-demand LLM analysis of an already-cited YouTube video: why it works as a citation source, the brands it treats, and an internal creator pre-brief. Price a selection before committing to it, trigger the analyses, and read the results. - name: Creator Briefs description: >- Partnership briefs written for shortlisted YouTube creators: a markdown document with its brand context, saved and edited by the user, with one version recorded per save and the diff into each version stored at write time. - name: CSV Export description: >- Generic CSV export gateway shared across features. `export_type` selects which dataset to export; each feature registers its own export types and usecases on the same CsvExportUsecase base rather than duplicating the CSV-writing/validation mechanics. paths: /v1/organizations/{organization_id}/workspaces/{workspace_id}/search/analyses: post: tags: - Projects summary: Create Analysis description: >- Create a Search analysis in the workspace: brand, website, engines, country and language, and the prompts, each naming its thematic, its topic and the persona of the workspace library asking it. The first collection starts right away and the workspace is debited one search credit per prompt. 402 when the workspace has fewer search credits than prompts; 422 when an engine is not in the references for this organization or when a persona id is unknown. Returns the analysis as GET /analyses/{project_id} does. Restricted to editors and above. operationId: create_search_visibility_analysis parameters: - name: organization_id in: path required: true schema: type: string title: Organization Id - name: workspace_id in: path required: true schema: type: string title: Workspace Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAnalysisRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AnalysisDetailResponse' '402': description: >- The workspace has fewer search credits than the analysis has prompts. '403': description: The caller cannot write in this workspace. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] components: schemas: CreateAnalysisRequest: properties: website: type: string title: Website description: >- Website the analysis tracks, as a domain or subdomain (e.g. 'nike.com'). brand: type: string title: Brand description: Brand name to track, as users write it. country: type: string title: Country description: ISO 3166-1 alpha-2 country code of the collection (e.g. 'US'). language: type: string title: Language description: >- Language code of the prompts (e.g. 'en'); the country-language pair must be one of the references. sources: items: $ref: '#/components/schemas/SourcesEnum' type: array title: Sources description: >- Engines to collect, by id as listed by the references (e.g. 'ChatGPT', 'Gemini'). At least one. prompts: items: $ref: '#/components/schemas/PromptRequest' type: array title: Prompts description: >- Prompts to collect, each naming its thematic, its topic and its persona. At least one. The thematics and topics are created from the distinct names, in order of first appearance. name: type: string nullable: true title: Name description: >- Display name of the analysis. Defaults to ' - '. brand_official_name: type: string nullable: true title: Brand Official Name description: >- Official or legal name of the brand when it differs from the display name. category: type: string nullable: true title: Category description: >- Industry or vertical of the brand (e.g. 'Running shoes'). Defaults to Uncategorized. frequency: allOf: - $ref: '#/components/schemas/FrequencyEnum' nullable: true description: >- Collection frequency, by id as listed by the references. Defaults to ONCE. query_fanouts_enabled: type: boolean title: Query Fanouts Enabled description: >- Whether to collect the query fan-outs (the sub-queries the engines run). default: false type: object required: - website - brand - country - language - sources - prompts title: CreateAnalysisRequest description: >- The body of `POST /analyses`: the setup an agent builds. The workspace is the path's, the thematics and topics come from the prompts, every id is generated, the device is desktop. example: brand: Nike brand_official_name: Nike, Inc. category: Running shoes country: US frequency: ONCE language: en prompts: - funnel_stage: MoFu persona_id: 4f2d9a6e-1b3c-4d5e-8f70-1a2b3c4d5e6f strength: cushioning text: best running shoes for daily training thematic: Running shoes topic: Daily trainers - brand_type: Brand funnel_stage: ToFu persona_id: 4f2d9a6e-1b3c-4d5e-8f70-1a2b3c4d5e6f text: are nike pegasus good for beginners thematic: Running shoes topic: Daily trainers - funnel_stage: MoFu persona_id: 4f2d9a6e-1b3c-4d5e-8f70-1a2b3c4d5e6f text: best shoes for a first marathon thematic: Running shoes topic: Racing weakness: price sources: - ChatGPT - Gemini - Perplexity website: nike.com AnalysisDetailResponse: properties: id: type: string title: Id description: Unique identifier of the analysis. internal_id: type: string title: Internal Id description: UUID v4 unique identifier of the analysis. deprecated: true workspace_id: type: string nullable: true title: Workspace Id description: ID of the workspace this analysis belongs to. name: type: string nullable: true title: Name description: Display name of the analysis, if set. website: type: string title: Website description: Website being tracked by this analysis. brand: type: string title: Brand description: Primary brand name associated with the tracked website. brand_official_name: type: string nullable: true title: Brand Official Name description: >- Official legal or full name of the brand, if different from the display name. status: allOf: - $ref: '#/components/schemas/ProjectStatusEnum' description: Lifecycle status of the analysis. sources: items: $ref: '#/components/schemas/SourcesEnum' type: array title: Sources description: Search engines and AI sources monitored by this analysis. devices: items: $ref: '#/components/schemas/DevicesEnum' type: array title: Devices description: Device types for which results are collected. country: type: string title: Country description: >- Country code for which search results are collected (ISO 3166-1 alpha-2). language: type: string title: Language description: Language code used for queries in this analysis (BCP 47). frequency: allOf: - $ref: '#/components/schemas/FrequencyEnum' description: How often data collection runs. website_type: allOf: - $ref: '#/components/schemas/WebsiteType' nullable: true description: Type of website being tracked. Null if not specified. query_fanouts_enabled: type: boolean title: Query Fanouts Enabled description: >- Whether query fan-out (expanded query variants) is enabled for this analysis. category: type: string title: Category description: Industry or vertical category this analysis belongs to. thematics: items: $ref: '#/components/schemas/AnalysisThematicResponse' type: array title: Thematics description: >- Thematic groups defined in this analysis, each containing topics with their keywords. personas: items: $ref: '#/components/schemas/AnalysisPersonaResponse' type: array title: Personas description: Personas defined for this analysis. default: [] related_products: items: $ref: '#/components/schemas/AnalysisRelatedProductResponse' type: array title: Related Products description: Products or services linked to this analysis. default: [] sub_brands: items: $ref: '#/components/schemas/AnalysisSubBrandResponse' type: array title: Sub Brands description: Sub-brands tracked within this analysis. default: [] perceptions: items: $ref: '#/components/schemas/AnalysisPerceptionResponse' type: array title: Perceptions description: Brand strengths and weaknesses defined for this analysis. default: [] created_at: type: string title: Created At description: ISO 8601 timestamp of when this analysis was created. updated_at: type: string title: Updated At description: ISO 8601 timestamp of when this analysis was last updated. type: object required: - id - internal_id - website - brand - status - sources - devices - country - language - frequency - query_fanouts_enabled - category - thematics - created_at - updated_at title: AnalysisDetailResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SourcesEnum: type: string enum: - Bing - BingAIO - ChatGPT - Perplexity - Google - GoogleAIO - GoogleAIMode - Claude - Gemini - AmazonRufus - Grok - Copilot - Mistral - MuseSpark title: SourcesEnum PromptRequest: properties: text: type: string title: Text description: The prompt to collect, as a user would type it in the engines. thematic: type: string title: Thematic description: >- Thematic of the prompt. Prompts naming the same thematic (case and spaces aside) share it. topic: type: string title: Topic description: >- Topic of the prompt inside its thematic. Prompts naming the same topic under the same thematic share it. persona_id: type: string title: Persona Id description: >- Id of the persona asking this prompt, from the workspace's persona library (list_personas). funnel_stage: allOf: - $ref: '#/components/schemas/FunnelStage' nullable: true description: 'Funnel stage of the prompt: ToFu, MoFu or BoFu.' brand_type: allOf: - $ref: '#/components/schemas/KeywordOverviewMetricTypeEnum' description: >- Brand when the prompt names the brand or one of its products, Generic otherwise (the default). default: Generic strength: type: string nullable: true title: Strength description: >- Perceived strength of the brand this prompt probes (e.g. 'cushioning'). Prompts naming the same strength share it. weakness: type: string nullable: true title: Weakness description: >- Perceived weakness of the brand this prompt probes (e.g. 'price'). Prompts naming the same weakness share it. type: object required: - text - thematic - topic - persona_id title: PromptRequest FrequencyEnum: type: string enum: - MONTHLY - WEEKLY - DAILY - ONCE title: FrequencyEnum ProjectStatusEnum: type: string enum: - ACTIVE - DELETED - PAUSED title: ProjectStatusEnum DevicesEnum: type: string enum: - DESKTOP - MOBILE - TABLET title: DevicesEnum WebsiteType: type: string enum: - DOMAIN - SUBDOMAIN title: WebsiteType AnalysisThematicResponse: properties: id: type: string title: Id description: Unique identifier of the thematic group. name: type: string title: Name description: Display name of the thematic group. color: type: string title: Color description: Hex colour code used to represent this thematic in the UI. topics: items: $ref: '#/components/schemas/AnalysisTopicResponse' type: array title: Topics description: Topics defined within this thematic group. default: [] type: object required: - id - name - color title: AnalysisThematicResponse AnalysisPersonaResponse: properties: id: type: string title: Id description: Unique identifier of the persona. label: type: string title: Label description: Short display name for the persona. description: type: string title: Description description: Longer description of the persona's profile and characteristics. core_needs: items: type: string type: array title: Core Needs description: Key needs or motivations associated with this persona. default: [] pain_points: items: type: string type: array title: Pain Points description: Challenges or frustrations associated with this persona. default: [] profile_archetype: type: string nullable: true title: Profile Archetype description: The persona's archetype name. demographic_occupation: type: string nullable: true title: Demographic Occupation description: The persona's occupation. demographic_age_from: type: string nullable: true title: Demographic Age From description: Lower bound of the persona's age range. demographic_age_to: type: string nullable: true title: Demographic Age To description: Upper bound of the persona's age range. demographic_gender: type: string nullable: true title: Demographic Gender description: The persona's gender. demographic_living_context: type: string nullable: true title: Demographic Living Context description: Where/how the persona lives. demographic_education_level: type: string nullable: true title: Demographic Education Level description: The persona's education level. demographic_education_field: type: string nullable: true title: Demographic Education Field description: The persona's field of study. demographic_income_from: type: string nullable: true title: Demographic Income From description: Lower bound of income range. demographic_income_to: type: string nullable: true title: Demographic Income To description: Upper bound of income range. internal_compass_values_and_personality_traits: type: string nullable: true title: Internal Compass Values And Personality Traits description: The persona's values and personality traits. internal_compass_motivations: type: string nullable: true title: Internal Compass Motivations description: What motivates the persona. internal_compass_strategic_goal: type: string nullable: true title: Internal Compass Strategic Goal description: The persona's overarching strategic goal. job_to_be_done: type: string nullable: true title: Job To Be Done description: The job the persona is trying to get done. resistance_core_questions: type: string nullable: true title: Resistance Core Questions description: Questions the persona keeps coming back to before buying. resistance_pain_points: type: string nullable: true title: Resistance Pain Points description: What frustrates or worries the persona about buying. resistance_purchase_barriers: type: string nullable: true title: Resistance Purchase Barriers description: What's holding the persona back from purchasing. resistance_key_buying_triggers: type: string nullable: true title: Resistance Key Buying Triggers description: What would finally get the persona to act. behavioural_map_lifestyle_and_primary_tasks: type: string nullable: true title: Behavioural Map Lifestyle And Primary Tasks description: The persona's lifestyle and primary daily tasks. behavioural_map_media_consumption: type: string nullable: true title: Behavioural Map Media Consumption description: The persona's media and information diet. behavioural_map_typical_quote: type: string nullable: true title: Behavioural Map Typical Quote description: A quote in the persona's own voice and register. connection_why_loves_category: type: string nullable: true title: Connection Why Loves Category description: Why this category matters to the persona. connection_product_need: type: string nullable: true title: Connection Product Need description: What the persona needs from a product in this space. type: object required: - id - label - description title: AnalysisPersonaResponse AnalysisRelatedProductResponse: properties: id: type: string title: Id description: Unique identifier of the related product. name: type: string title: Name description: Name of the product or service related to this analysis. type: object required: - id - name title: AnalysisRelatedProductResponse AnalysisSubBrandResponse: properties: id: type: string title: Id description: Unique identifier of the sub-brand. name: type: string title: Name description: Name of the sub-brand. type: object required: - id - name title: AnalysisSubBrandResponse AnalysisPerceptionResponse: properties: id: type: string title: Id description: Unique identifier of the perception entry. value: type: string title: Value description: Text describing the perceived strength or weakness. type: type: string enum: - strength - weakness title: Type description: Whether this perception is a brand strength or a brand weakness. type: object required: - id - value - type title: AnalysisPerceptionResponse ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError FunnelStage: type: string enum: - ToFu - MoFu - BoFu title: FunnelStage KeywordOverviewMetricTypeEnum: type: string enum: - Generic - Brand title: KeywordOverviewMetricTypeEnum AnalysisTopicResponse: properties: id: type: string title: Id description: Unique identifier of the topic. thematic_id: type: string title: Thematic Id description: ID of the thematic group this topic belongs to. text: type: string title: Text description: Label or name of the topic. keywords: items: $ref: '#/components/schemas/AnalysisKeywordResponse' type: array title: Keywords description: Keywords assigned to this topic. default: [] type: object required: - id - thematic_id - text title: AnalysisTopicResponse AnalysisKeywordResponse: properties: id: type: string title: Id description: Unique identifier of the keyword. text: type: string title: Text description: Keyword text as it is tracked and queried. brand_type: type: string nullable: true title: Brand Type description: >- Brand classification of the keyword (e.g. 'branded', 'competitor', 'generic'). Null if unclassified. type: object required: - id - text title: AnalysisKeywordResponse securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.