Get complete results from all searches in a group

Retrieve and compare actual search results across multiple searches in a group

This endpoint returns the complete candidate results from every search in a group, allowing you to compare which candidates were found by each search type and analyze result quality side-by-side.

What Does This Endpoint Return?

Unlike the group status endpoint which only shows metadata, this endpoint returns the actual candidate results from each search, including:

• ✅ Full candidate profiles (name, contact, experience)
• ✅ Complete CV text (extractedText)
• ✅ Relevance scores for each candidate
• ✅ Complete result sets from each search type
• ✅ Processing times and performance metrics
• ✅ Applied filters for each search

Prerequisites

• All searches should be completed - Check status first using GET /v1/public/searches/groups/{searchGroupId}
• Searches must belong to your company

Note: If some searches are still processing, this endpoint returns HTTP 202 with partial information. Wait for completion to get full results.

Response Structure

Example Response

{
  "searchGroupId": "e1de299b-8cb3-4d56-9f9b-fc58c8c59841",
  "query": "ai engineer",
  "groupStatus": "completed",
  "searches": [
    {
      "searchId": "4c4b15e0-032d-43e9-b41b-ef3a2efa2e84",
      "searchType": "dense",
      "status": "completed",
      "query": "ai engineer",
      "results": [
        {
          "documentId": "uuid",
          "documentName": "John_Doe_CV.pdf",
          "documentDate": "11-2025",
          "score": 0.856,
          "extractedText": "John Doe\nSenior AI Engineer\nParis, France...",
          "summary": "John Doe - Technology Professional based in Paris...",
          "contact": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "john@example.com",
            "linkedin": "linkedin.com/in/johndoe",
            "location": { "city": "Paris", "country": "FRA" }
          },
          "profile": {
            "domain": "Technology",
            "specialization": "AI Engineering",
            "seniorityLevel": "Senior",
            "experienceYears": 8,
            "technicalStack": ["Python", "TensorFlow", "PyTorch"],
            "industries": ["Tech", "Finance"],
            "recentExpertise": ["Machine Learning", "Deep Learning"],
            "hasManagement": true
          },
          "attributes": {
            "languages": { "english": 1, "french": 1 },
            "technical_skills": { "python_experience": 1 },
            "education_indicators": { "highest_degree": "Master" }
          }
        }
      ],
      "totalResults": 15,
      "processingTimeMs": 1763,
      "error": null,
      "filters": {
        "intelligentFilters": {},
        "appliedFilters": {}
      },
      "completedAt": "2025-11-04T14:21:58.018Z"
    },
    {
      "searchId": "54153a24-c8e5-4eb6-997c-9a8d0f1216e2",
      "searchType": "sparse",
      "status": "completed",
      "query": "ai engineer",
      "results": [ /* Same format as above */ ],
      "totalResults": 12,
      "processingTimeMs": 351,
      "error": null,
      "filters": {},
      "completedAt": "2025-11-04T14:22:07.957Z"
    }
  ],
  "summary": {
    "totalSearches": 2,
    "completedSearches": 2,
    "failedSearches": 0,
    "totalProcessingTimeMs": 2114,
    "averageProcessingTimeMs": 1057
  },
  "metadata": {
    "createdAt": "2025-11-04T14:21:55.139Z",
    "firstCompletedAt": "2025-11-04T14:21:58.018Z",
    "lastCompletedAt": "2025-11-04T14:22:07.957Z"
  }
}

Field Descriptions

Top-Level Fields

Search Results Object

Each item in the searches array contains:

Result Items (Candidates)

Each candidate in the results array includes:

Document Information:

• documentId - CV document identifier (UUID)
• documentName - CV filename
• documentDate - CV date (MM-YYYY format)
• score - Relevance score (0-1, higher = better)

Full Content:

• extractedText - Complete CV text (5-15KB per candidate)
• summary - AI-generated professional summary

Contact Information:

• contact.firstName - First name
• contact.lastName - Last name
• contact.email - Email address
• contact.linkedin - LinkedIn profile URL
• contact.location.city - Current city
• contact.location.country - Country (ISO code)

Professional Profile:

• profile.domain - Primary domain (e.g., "Technology")
• profile.specialization - Specific expertise area
• profile.seniorityLevel - Career level: Junior/Senior/Executive
• profile.experienceYears - Total years of experience
• profile.technicalStack - Array of technologies/tools
• profile.industries - Array of industry verticals
• profile.recentExpertise - Recent areas of focus
• profile.hasManagement - Has leadership experience

Detailed Attributes:

• attributes.languages - Language proficiency
• attributes.market_client - Market experience
• attributes.certifications - Certification counts
• attributes.domain_analysis - Domain categorization
• attributes.technical_skills - Technical skill flags
• attributes.industry_verticals - Industry experience
• attributes.education_indicators - Education details
• attributes.professional_experience - Career metrics

For complete field descriptions, see GET /v1/public/searches/{searchId}/results documentation.

Summary Statistics

Metadata

Status Handling

If Searches Still Processing

If any search is still running, the endpoint returns HTTP 202:

{
  "searchGroupId": "uuid",
  "status": "processing",
  "message": "Some searches in the group are still processing",
  "searches": [
    {
      "searchId": "uuid",
      "searchType": "dense",
      "status": "completed",
      "statusUrl": "/v1/public/searches/{searchId}"
    },
    {
      "searchId": "uuid",
      "searchType": "hybrid",
      "status": "processing",
      "statusUrl": "/v1/public/searches/{searchId}"
    }
  ]
}

Action: Poll the group status endpoint until groupStatus is completed or partial, then retry this endpoint.

Algorithm Selection Guide

Use the comparison results to choose the best algorithm:

Choose Dense if:

• ✅ Natural language queries are common
• ✅ Speed is important (typically fastest)
• ✅ Semantic understanding matters more than exact keywords
• ✅ Queries are conversational (e.g., "experienced engineer with startup background")

Choose Sparse if:

• ✅ Exact keyword matching is needed
• ✅ Technical skill searches (e.g., "Python Django PostgreSQL")
• ✅ Speed is critical (second fastest)
• ✅ Queries are keyword-based

Choose Hybrid if:

• ✅ Quality is more important than speed
• ✅ Complex queries with mixed requirements
• ✅ Willing to wait 15-30 seconds for best results
• ✅ Need both semantic and keyword matching

Choose Builtin-Rerank if:

• ✅ Want semantic search with quality boost
• ✅ Need middle-ground between speed and quality
• ✅ Cost-conscious (cheaper than full hybrid)
• ✅ Want better than dense without full hybrid cost

Performance Notes

Response Size:

• Small group (2-3 searches with 10 results each): ~200-400KB
• Large group (4 searches with 20 results each): ~800KB-1.2MB
• Size depends on: number of searches × candidates per search × extractedText size (~15KB per candidate)

Response Time:

• Fast retrieval (~100-500ms) - just database reads
• No search re-execution - results are pre-computed and stored
• Safe to call multiple times without performance penalty

How It Works:

1. When searches complete, results (including extractedText) are saved to database
2. This endpoint reads those saved results
3. Transforms and cleans the data
4. Aggregates into a single response
5. No additional processing or re-searching occurs

Safe to Call:

• ✅ Multiple times (reads from database, doesn't re-run searches)
• ✅ From multiple clients (results don't change)
• ✅ For caching/offline access (results are stable)

Error Handling

404 - Group Not Found

{
  "error": "Search group not found",
  "searchGroupId": "uuid"
}

Reasons:

• Invalid searchGroupId
• Group doesn't belong to your company
• No searches exist with this group ID

202 - Still Processing

{
  "searchGroupId": "uuid",
  "status": "processing",
  "message": "Some searches in the group are still processing",
  "searches": [ ... ]
}

Action: Wait and retry, or poll the group status endpoint

500 - Server Error

{
  "error": "Failed to get search group results",
  "message": "Error details"
}

Action: Retry request or contact support

Related Endpoints

• GET /v1/public/searches/groups/{searchGroupId} - Check group status (use before this endpoint)
• GET /v1/public/searches/{searchId}/results - Get results from individual search
• POST /v1/public/searches/{type} - Initiate searches with searchGroupId to create groups

Pro Tips

💡 Analysis:

• Run comparisons on 5-10 representative queries from your domain
• Look for patterns in which algorithm performs best
• Check if algorithms agree on top candidates (high confidence indicator)
• Unique finds reveal each algorithm's strengths
• Use extractedText for custom analysis not available in structured fields

💡 Performance:

• Dense and Sparse typically complete in 0.3-2s
• Hybrid takes 15-30s but often finds best candidates
• Builtin-Rerank is good middle ground at 3-8s
• Endpoint response is fast since data is pre-computed

💡 Quality Signals:

• Candidates appearing in top 5 across ALL algorithms = very strong matches
• High overlap between algorithms = consistent quality
• Unique finds from Hybrid often reveal hidden gems
• Low overlap might indicate query ambiguity

💡 Integration:

• Use comparison data to document algorithm behavior
• Build dashboards showing algorithm performance over time
• Train teams on when to use each algorithm
• Set up automated tests comparing algorithms on sample queries
• Parse extractedText for custom fields not in structured data

curl -X GET "https://api.floreal.ai/v1/public/searches/groups/497f6eca-6276-4993-bfeb-53cbbbba6f08/results"

{
  "searchGroupId": "6057d3c7-e3bb-4624-80c0-432d9633004b",
  "query": "string",
  "groupStatus": "completed",
  "searches": [
    {
      "searchId": "9b1a67f9-9477-48e5-8a6c-11b70245e1d9",
      "searchType": "dense",
      "status": "completed",
      "query": "string",
      "results": [
        {
          "documentId": "4704590c-004e-410d-adf7-acb7ca0a7052",
          "documentName": "string",
          "documentDate": "string",
          "score": 0,
          "extractedText": "string",
          "summary": "string",
          "contact": {
            "firstName": "string",
            "lastName": "string",
            "email": "string",
            "linkedin": "string",
            "location": {
              "city": "string",
              "country": "string"
            }
          },
          "profile": {
            "domain": "string",
            "specialization": "string",
            "seniorityLevel": "string",
            "experienceYears": 0,
            "technicalStack": [
              "string"
            ],
            "industries": [
              "string"
            ],
            "recentExpertise": [
              "string"
            ],
            "hasManagement": true
          },
          "attributes": {}
        }
      ],
      "totalResults": 0,
      "processingTimeMs": 0,
      "error": "string",
      "filters": {
        "intelligentFilters": {},
        "appliedFilters": {}
      },
      "completedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "summary": {
    "totalSearches": 0,
    "completedSearches": 0,
    "failedSearches": 0,
    "totalProcessingTimeMs": 0,
    "averageProcessingTimeMs": 0
  },
  "metadata": {
    "createdAt": "2019-08-24T14:15:22Z",
    "firstCompletedAt": "2019-08-24T14:15:22Z",
    "lastCompletedAt": "2019-08-24T14:15:22Z"
  }
}

{
  "error": "string",
  "message": "string"
}

{
  "error": "string"
}

{
  "error": "string",
  "message": "string"
}