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

# Filter Builder API

> Convert a natural language description of target companies into a structured filters object for use with the List Generation API.

## Overview

The Filter Builder API converts a free-text description of your target companies into the structured `filters` object accepted by the [List Generation API](/api-reference/listgen-api). Use it when you want the precision and reproducibility of structured filters, but would rather describe your target companies in plain English than look up enum values, industry codes, and filter keys yourself.

The endpoint does not return any companies itself. It only returns the equivalent `filters` object. Pass that object straight into the `filters` parameter of a subsequent `/v1/company/list/generate` call to fetch the actual matching companies.

## Endpoint Details

* **Method:** POST
* **Endpoint:** `/api/v1/list/filter-builder/`

## Authentication requirements

* Include a valid API key in the `x-api-key` request header.

## Request

### Request Parameters

#### Header Parameters

<ParamField header="x-api-key" type="string" required>
  Your API key.
</ParamField>

#### Body Parameters

<ParamField body="query" type="string" required>
  Natural language description of your target companies (e.g. "series a companies in mumbai working in climate tech").

  The API interprets location, funding stage, industry, and other filterable attributes mentioned in the query and resolves them to the corresponding structured filter keys and values used by the List Generation API.
</ParamField>

## Response

#### Successful Response Fields

<ResponseField name="data" type="object">
  Container for the translated result. Contains `filters` key that includes all the translated filters.

  <ResponseField name="filters" type="object">
    The structured filters object equivalent to the input query, using the same dotted-path filter keys as the [List Generation API](/api-reference/listgen-api) (e.g. `location.hq.city`, `funding_detail.funding_overview.funding_stage`, `industry.industry`).

    Only the filter groups relevant to the query are included. Pass this object directly into the `filters` parameter of a List Generation API request.
  </ResponseField>
</ResponseField>

<ResponseField name="credits_consumed" type="float">
  Number of credits consumed by this request. See [Pricing](/getting-started/pricing) for the full credit breakdown.
</ResponseField>

<ResponseExample>
  ```json 200 expandable wrap theme={null}
  {
    "data": {
      "filters": {
        "location.hq.city": [
          "Mumbai"
        ],
        "funding_detail.funding_overview.funding_stage": [
          "series_a"
        ],
        "industry.industry": [
          "EUAB",
          "EUACAJ",
          "EUAAAL",
          "EUAFAN",
          "EUAFAF"
        ]
      }
    },
    "credits_consumed": 2.5
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /v1/list/filter-builder/
openapi: 3.0.3
info:
  title: Akta.pro API
  description: >
    Akta provides APIs for company intelligence and news monitoring:


    1. **News** – Enriched news articles with AI summaries, sentiment, event
    tags, industry classifications, and company mention resolution.

    2. **Company Enrichment** – Structured company data including firmographics,
    funding, headcount, and financials.

    3. **Company Search** – Free endpoint to resolve company names, domains, or
    UUIDs.

    4. **Product Reviews** – G2 product reviews with ratings and review content.

    5. **Employee Reviews** – Employee sentiment data with workplace ratings.


    **Authentication:** All endpoints require an API key in the `x-api-key` HTTP
    header.
  version: 1.0.0
  contact:
    url: https://akta.pro
servers:
  - url: https://api.akta.pro/api
    description: Production server
security: []
tags:
  - name: News
    description: Enriched news articles with AI summaries, sentiment, and company mentions
  - name: Company
    description: Company data enrichment, search, and addition
  - name: Reviews
    description: Product and employee reviews from external sources
  - name: Supporting APIs
    description: Utility endpoints for request tracking
  - name: List Generation
    description: >-
      Build targeted company lists using structured filters or natural language
      queries
externalDocs:
  description: Official Akta.pro API Documentation
  url: https://docs.akta.pro
paths:
  /v1/list/filter-builder/:
    post:
      tags:
        - List Generation
      description: >-
        Converts natural language queries into structured filter conditions for
        the List Generation API.
      operationId: translateQuery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslateQueryRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslateQueryResponse'
      security:
        - xApiKeyAuth: []
components:
  schemas:
    TranslateQueryRequest:
      type: object
      properties:
        query:
          type: string
          description: >-
            Natural language description of target companies (e.g. 'series a
            companies in mumbai working in climate tech').
      required:
        - query
    TranslateQueryResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            filters:
              type: object
              description: >-
                Structured filters object equivalent to the input query, using
                dotted-path filter keys.
        credits_consumed:
          type: number
          format: float
  securitySchemes:
    xApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key obtained from your Akta account.

````