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

# Audience composition breakdown API

> Group an audience along one dimension — country, industry, employees, company type, language, declared country, or technology category. Costs 1 credit.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Which dimensions are available?">
    Company dimensions — `country`, `industry`, `employees`, `company_type`. Website dimensions from the crawl — `language`, `web_country`. And `category`, which rolls the group's technology stack up per category instead of profiling the companies.
  </Accordion>

  <Accordion title="Why are values lowercase?">
    Company dimensions group by normalized values, because raw source values are case-split — 'United States' and 'united states' would otherwise be two rows. Display uses the same vocabulary the filters accept, so a value you see here can be pasted straight back into a filter.
  </Accordion>

  <Accordion title="What is matched, and why is it lower than total?">
    `total` is the audience size; `matched` is how many members have data on the dimension you asked for, and it is the denominator for `share_of_matched`. Company dimensions only cover members with a matched company record, which is roughly 23–30% of technology domains.
  </Accordion>

  <Accordion title="Why does by=category exist when the technology report has categories?">
    Because summing per-technology counts double-counts domains running more than one tool in a category. `by=category` computes distinct domains per category server-side, which is the number you actually want.
  </Accordion>

  <Accordion title="Can I combine a breakdown with a filter?">
    Yes — the same inline firmographic parameters work here, so "the industry breakdown of the US slice of my list" is a single request.
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml GET /v1/segments/{id}/breakdown
openapi: 3.1.0
info:
  title: TechnologyChecker API
  description: >-
    Discover technology stacks, track market trends, and enrich data with
    company intelligence.
  version: 1.0.0
  contact:
    name: TechnologyChecker Support
    email: support@technologychecker.io
    url: https://technologychecker.io
servers:
  - url: https://api.technologychecker.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Domain technologies
    description: Look up technologies detected on any domain
  - name: Technology data
    description: Search, look up, and get details on tracked technologies
  - name: Market intelligence
    description: Technology stats, trends, and market share
  - name: Company data
    description: Firmographic and company intelligence
  - name: Live detection
    description: Real-time technology detection with browser rendering
  - name: Signals
    description: >-
      Intent signals derived from technology state transitions: who adopted, who
      churned, who switched, and who has a gap in their stack.
  - name: Alerts
    description: >-
      Saved signal queries delivered to your webhook. Every signal you can
      query, you can subscribe to.
  - name: Audiences
    description: >-
      Saved groups of domains — uploaded lists or computed recipes — that you
      can profile, slice and monitor.
  - name: Lead lists
    description: >-
      Build and export targeted domain lists combining technology detection with
      company data.
paths:
  /v1/segments/{id}/breakdown:
    get:
      tags:
        - Audiences
      summary: Audience composition breakdown API
      description: >-
        Who is in this group — its composition along one dimension. Firmographic
        dimensions group members by normalized values, so display shares the
        same vocabulary the filters take. `by=category` instead rolls the
        group's stack up per category using server-side distinct-domain counts,
        which is the correct way to do it: summing the technology report's
        per-technology numbers double-counts domains running more than one tool
        in a category.


        Composable with the same inline firmographic parameters as the
        technology report, so you can ask for the industry breakdown of the US
        slice.


        Costs 1 credit.
      operationId: getAudienceBreakdown
      parameters:
        - name: id
          in: path
          required: true
          description: The audience id.
          schema:
            type: string
            example: seg_8f3a2c1b
        - name: by
          in: query
          required: true
          description: The dimension to group by.
          schema:
            type: string
            enum:
              - country
              - industry
              - employees
              - company_type
              - language
              - web_country
              - category
            example: country
        - $ref: '#/components/parameters/FirmoCountry'
        - $ref: '#/components/parameters/FirmoCity'
        - $ref: '#/components/parameters/FirmoState'
        - $ref: '#/components/parameters/FirmoIndustry'
        - $ref: '#/components/parameters/FirmoIndustryCode'
        - $ref: '#/components/parameters/FirmoEmployees'
        - $ref: '#/components/parameters/FirmoCompanyType'
        - $ref: '#/components/parameters/FirmoFoundedMin'
        - $ref: '#/components/parameters/FirmoFoundedMax'
        - $ref: '#/components/parameters/WebHasEmail'
        - $ref: '#/components/parameters/WebHasPhone'
        - $ref: '#/components/parameters/WebSocial'
        - $ref: '#/components/parameters/WebLanguage'
        - $ref: '#/components/parameters/WebCountry'
      responses:
        '200':
          description: Member counts and shares per dimension value, top 50
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      segment:
                        type: object
                      by:
                        type: string
                        example: country
                      total:
                        type: integer
                        example: 5914
                      matched:
                        type: integer
                        description: >-
                          Members with data on this dimension. This is the share
                          denominator.
                        example: 4459
                      coverage_note:
                        type: string
                      firmographics:
                        $ref: '#/components/schemas/FirmographicsEcho'
                      breakdown:
                        type: array
                        items:
                          type: object
                          properties:
                            value:
                              type: string
                              example: united states
                            members:
                              type: integer
                              example: 3091
                            share_of_matched:
                              type: number
                              format: float
                              nullable: true
                              example: 0.693
                      count:
                        type: integer
                        example: 50
                      generated_at:
                        type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/QueryTimeout'
components:
  parameters:
    FirmoCountry:
      name: country
      in: query
      required: false
      description: Filter to companies in this country (case-insensitive).
      schema:
        type: string
      example: united states
    FirmoCity:
      name: city
      in: query
      required: false
      description: Filter to companies in this city (case-insensitive).
      schema:
        type: string
    FirmoState:
      name: state
      in: query
      required: false
      description: Filter to companies in this state or region (case-insensitive).
      schema:
        type: string
    FirmoIndustry:
      name: industry
      in: query
      required: false
      description: Filter to companies in this industry (case-insensitive).
      schema:
        type: string
      example: retail
    FirmoIndustryCode:
      name: industry_code
      in: query
      required: false
      description: Filter by exact LinkedIn industry code.
      schema:
        type: integer
    FirmoEmployees:
      name: employees
      in: query
      required: false
      description: >-
        Filter by exact LinkedIn employee band. Unknown bands are rejected with
        `INVALID_EMPLOYEE_BAND` and the allowed list.
      schema:
        type: string
      example: 51-200
    FirmoCompanyType:
      name: company_type
      in: query
      required: false
      description: Filter by exact company type.
      schema:
        type: string
      example: Privately Held
    FirmoFoundedMin:
      name: founded_min
      in: query
      required: false
      description: Only companies founded in or after this year.
      schema:
        type: integer
        minimum: 1800
        maximum: 2025
    FirmoFoundedMax:
      name: founded_max
      in: query
      required: false
      description: Only companies founded in or before this year.
      schema:
        type: integer
        minimum: 1800
        maximum: 2025
    WebHasEmail:
      name: has_email
      in: query
      required: false
      description: >-
        Filter to domains where the crawler found (or did not find) an email
        address. `false` is a real filter, not a no-op.
      schema:
        type: boolean
    WebHasPhone:
      name: has_phone
      in: query
      required: false
      description: >-
        Filter to domains where the crawler found (or did not find) a phone
        number.
      schema:
        type: boolean
    WebSocial:
      name: social
      in: query
      required: false
      description: Filter to domains publishing a profile on this platform.
      schema:
        type: string
        enum:
          - linkedin
          - x
          - facebook
          - instagram
          - youtube
          - github
          - tiktok
          - discord
          - reddit
          - crunchbase
          - slack
      example: instagram
    WebLanguage:
      name: language
      in: query
      required: false
      description: Filter by the site's primary language.
      schema:
        type: string
      example: de
    WebCountry:
      name: web_country
      in: query
      required: false
      description: >-
        Filter by the country the site declares in its schema.org markup.
        Accepts ISO-2, English name or common variants.
      schema:
        type: string
      example: USA
  schemas:
    FirmographicsEcho:
      type: object
      description: Echo of the firmographic predicates that took effect on this request.
      properties:
        applied:
          type: object
          additionalProperties: true
          example:
            country: united states
            employees: 51-200
        filtered:
          type: boolean
          description: >-
            `true` when results were narrowed to matched companies; `false` for
            enrich-only (`company=true`).
          example: true
        note:
          type: string
          example: >-
            Results are limited to domains with a matched LinkedIn company that
            passes these filters (~23–30% of tech-domains have a company match).
    ApiError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: UNAUTHORIZED
            message:
              type: string
              example: Missing or invalid API key
  responses:
    BadRequest:
      description: Invalid or missing parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: >-
                Provide exactly one scope: technology_id, technology or
                category_id.
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    PaymentRequired:
      description: Not enough credits, or the plan does not include this feature
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: INSUFFICIENT_CREDITS
              message: Insufficient credits for this request.
              details:
                required: 1
                available: 0
    Forbidden:
      description: The plan does not allow this action, or a plan limit was reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: PLAN_LIMIT
              message: >-
                Your plan allows up to 2 saved audiences. Delete one to create
                another.
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    QueryTimeout:
      description: >-
        The query exceeded the 30-second server-side limit. Narrow the query and
        retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            success: false
            error:
              code: SEGMENT_QUERY_TIMEOUT
              message: The segment query exceeded the 30s server-side limit.
              details:
                suggestion: >-
                  Narrow the segment — add an employees band, industry, or city
                  — and try again.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key in format `tapi_live_[32-char]` (live) or `tapi_test_[32-char]`
        (test)

````