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

# Get Analytics

> Get organization usage, activity, and engagement with your organization API key. Sandbox returns fictional data; production requires production API and analytics access. See the [Analytics guide](/docs/analytics) to get started.

Requests that are too complex are rejected. Shorten the timeframe, or adjust the filters or breakdown as indicated by the error message.



## OpenAPI

````yaml GET /analytics
openapi: 3.0.1
info:
  title: Collective Work Job API
  description: API for managing job postings on the Collective Work platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.collective.work/{environment}/v1
    description: Collective Work API server
    variables:
      environment:
        default: sandbox
        description: API environment
        enum:
          - sandbox
          - production
security:
  - bearerAuth: []
paths:
  /analytics:
    get:
      tags:
        - analytics
      summary: Get analytics
      description: >-
        Get organization usage, activity, and engagement with your organization
        API key. Sandbox returns fictional data; production requires production
        API and analytics access. See the [Analytics guide](/docs/analytics) to
        get started.


        Requests that are too complex are rejected. Shorten the timeframe, or
        adjust the filters or breakdown as indicated by the error message.
      operationId: GetAnalyticsController_getAnalytics
      parameters:
        - in: query
          name: recruiterIds
          required: false
          description: >-
            IDs from the response’s recruiters array. Omit for everyone,
            including inactive members. Repeat for multiple IDs:
            recruiterIds=id1&recruiterIds=id2. Maximum 1,000 supplied values.
            Sandbox accepts only its fictional IDs.
          style: form
          explode: true
          schema:
            type: array
            maxItems: 1000
            items:
              type: string
              minLength: 1
          example:
            - cmubqjl3y0000uzcg6dbkeltw
            - cmubqjl3y0001uzcgasw32fpa
        - in: query
          name: breakdown
          required: false
          description: >-
            Time-series grouping in UTC. Weeks start Monday; months and years
            start on their first day.
          schema:
            type: string
            enum:
              - DAILY
              - WEEKLY
              - MONTHLY
              - YEARLY
            default: DAILY
        - in: query
          name: range
          required: false
          description: >-
            UTC date window. LAST_7/30_DAYS include today; THIS_MONTH/YEAR run
            through today; LAST_MONTH/YEAR cover the previous complete period.
            CUSTOM requires from and to. LAST_YEAR requires a non-daily
            breakdown.
          schema:
            type: string
            enum:
              - LAST_7_DAYS
              - LAST_30_DAYS
              - THIS_MONTH
              - LAST_MONTH
              - THIS_YEAR
              - LAST_YEAR
              - CUSTOM
            default: LAST_30_DAYS
        - in: query
          name: from
          required: false
          description: >-
            Inclusive UTC start date (YYYY-MM-DD). Required with CUSTOM;
            otherwise omit. Must be on or before to.
          schema:
            type: string
            format: date
            pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2026-09-07'
        - in: query
          name: to
          required: false
          description: >-
            Inclusive UTC end date (YYYY-MM-DD). Required with CUSTOM; otherwise
            omit.
          schema:
            type: string
            format: date
            pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2026-09-13'
        - in: query
          name: sections
          required: false
          description: >-
            Sections to return; omit for all four. Repeat to select several:
            sections=usage&sections=engagement. Maximum four supplied values.
          style: form
          explode: true
          schema:
            type: array
            maxItems: 4
            items:
              type: string
              enum:
                - usage
                - activity
                - engagement
                - recruiterSummary
          example:
            - usage
            - engagement
      responses:
        '200':
          description: >-
            Analytics retrieved. Example: all four sections for two sandbox
            recruiters over one week, including a recruiter with no activity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAnalyticsResponseDto'
              examples:
                All sections:
                  summary: All analytics sections
                  value:
                    recruiters:
                      - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                        email: alex.morgan@example.com
                        fullName: Alex Morgan
                      - recruiterId: cmubqjl3y0003uzcggumce0gq
                        email: taylor.brooks@example.com
                        fullName: Taylor Brooks
                    metadata:
                      organizationId: organization_example
                      requestedAt: '2026-09-14T09:00:00.000Z'
                      filters:
                        recruiterIds:
                          - cmubqjl3y0000uzcg6dbkeltw
                          - cmubqjl3y0003uzcggumce0gq
                        breakdown: WEEKLY
                        range: CUSTOM
                        from: '2026-09-07T00:00:00.000Z'
                        to: '2026-09-13T23:59:59.999Z'
                        sections:
                          - usage
                          - activity
                          - engagement
                          - recruiterSummary
                    sections:
                      usage:
                        profileViews:
                          total: 24
                          timeSeries:
                            - date: '2026-09-07T00:00:00.000Z'
                              total: 24
                          byRecruiter:
                            - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                              total: 24
                            - recruiterId: cmubqjl3y0003uzcggumce0gq
                              total: 0
                        sherlockQueries:
                          total: 8
                          timeSeries:
                            - date: '2026-09-07T00:00:00.000Z'
                              total: 8
                          byRecruiter:
                            - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                              total: 8
                            - recruiterId: cmubqjl3y0003uzcggumce0gq
                              total: 0
                        searchQueries:
                          total: 14
                          timeSeries:
                            - date: '2026-09-07T00:00:00.000Z'
                              total: 14
                          byRecruiter:
                            - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                              total: 14
                            - recruiterId: cmubqjl3y0003uzcggumce0gq
                              total: 0
                        postedJobs:
                          total: 1
                          timeSeries:
                            - date: '2026-09-07T00:00:00.000Z'
                              total: 1
                          byRecruiter:
                            - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                              total: 1
                            - recruiterId: cmubqjl3y0003uzcggumce0gq
                              total: 0
                        applications:
                          total: 4
                          timeSeries:
                            - date: '2026-09-07T00:00:00.000Z'
                              total: 4
                        sentMessages:
                          total: 12
                          timeSeries:
                            - date: '2026-09-07T00:00:00.000Z'
                              total: 12
                          byRecruiter:
                            - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                              total: 12
                            - recruiterId: cmubqjl3y0003uzcggumce0gq
                              total: 0
                        contactTracking:
                          total: 11
                          timeSeries:
                            - date: '2026-09-07T00:00:00.000Z'
                              total: 11
                          byRecruiter:
                            - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                              total: 11
                            - recruiterId: cmubqjl3y0003uzcggumce0gq
                              total: 0
                      activity:
                        sherlockQueries:
                          - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                            activeDays: 2
                          - recruiterId: cmubqjl3y0003uzcggumce0gq
                            activeDays: 0
                        searchQueries:
                          - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                            activeDays: 4
                          - recruiterId: cmubqjl3y0003uzcggumce0gq
                            activeDays: 0
                        postedJobs:
                          - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                            activeDays: 1
                          - recruiterId: cmubqjl3y0003uzcggumce0gq
                            activeDays: 0
                        sentMessages:
                          - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                            activeDays: 2
                          - recruiterId: cmubqjl3y0003uzcggumce0gq
                            activeDays: 0
                      engagement:
                        powerUsers:
                          count: 1
                          recruiters:
                            - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                              activeDays: 4
                              averageActiveDaysPerWeek: 4
                        regularUsers:
                          count: 0
                          recruiters: []
                        casualUsers:
                          count: 1
                          recruiters:
                            - recruiterId: cmubqjl3y0003uzcggumce0gq
                              activeDays: 0
                              averageActiveDaysPerWeek: 0
                      recruiterSummary:
                        - recruiterId: cmubqjl3y0000uzcg6dbkeltw
                          sherlockQueries: 8
                          searchQueries: 14
                          postedJobs: 1
                          sentMessages: 12
                          activeDays: 4
                        - recruiterId: cmubqjl3y0003uzcggumce0gq
                          sherlockQueries: 0
                          searchQueries: 0
                          postedJobs: 0
                          sentMessages: 0
                          activeDays: 0
        '400':
          description: >-
            Invalid or overly complex request. Follow the error message to
            correct the parameters or reduce the request’s scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsErrorResponseDto'
              examples:
                DATE_RANGE_TOO_LONG:
                  summary: A full year exceeds the daily date limit
                  value:
                    statusCode: 400
                    error: Bad Request
                    code: DATE_RANGE_TOO_LONG
                    message: >-
                      The DAILY breakdown supports at most 90 calendar days.
                      Reduce the date range or choose a coarser breakdown.
                    details:
                      requestedDays: 365
                      maxDays: 90
                      breakdown: DAILY
                QUERY_TOO_EXPENSIVE:
                  summary: Request is too complex
                  value:
                    statusCode: 400
                    error: Bad Request
                    code: QUERY_TOO_EXPENSIVE
                    message: >-
                      This request covers too many recruiters and dates. Reduce
                      the date range or filter recruiterIds.
                    details:
                      recruiterCount: 101
                      requestedDays: 365
                      requestedRecruiterDays: 36865
                      maxRecruiterDays: 36600
        '401':
          description: >-
            Missing or invalid API key, no organization recruiters, or
            production API access disabled. Sandbox does not require production
            access.
        '403':
          description: >-
            Production analytics access is disabled. Contact
            support@collective.work to enable it. Sandbox does not require this
            access.
components:
  schemas:
    GetAnalyticsResponseDto:
      type: object
      description: Analytics for the selected recruiters and UTC date range.
      required:
        - recruiters
        - metadata
        - sections
      properties:
        recruiters:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsRecruiterDto'
          description: >-
            Match section rows to these identities. Includes inactive and former
            members still attached to the organization.
        metadata:
          $ref: '#/components/schemas/AnalyticsMetadataDto'
        sections:
          $ref: '#/components/schemas/AnalyticsSectionsDto'
    AnalyticsErrorResponseDto:
      type: object
      description: Analytics validation error (HTTP 400).
      required:
        - statusCode
        - error
        - code
        - message
      properties:
        statusCode:
          type: number
          enum:
            - 400
          example: 400
        error:
          type: string
          enum:
            - Bad Request
          example: Bad Request
        code:
          type: string
          enum:
            - INVALID_PARAMETERS
            - INVALID_DATE_RANGE
            - DATE_RANGE_TOO_LONG
            - INVALID_RECRUITER_IDS
            - QUERY_TOO_EXPENSIVE
          description: >-
            INVALID_PARAMETERS: query validation, including oversized lists.
            INVALID_DATE_RANGE: invalid dates. DATE_RANGE_TOO_LONG: too many
            days. INVALID_RECRUITER_IDS: IDs unavailable in this
            organization/environment. QUERY_TOO_EXPENSIVE: request is too
            complex.
        message:
          type: string
          description: Explanation of the error. Use code for programmatic handling.
        details:
          type: object
          additionalProperties: true
          description: Optional information to help correct the request.
    AnalyticsRecruiterDto:
      type: object
      description: Selected recruiter identity; fictional in sandbox.
      required:
        - recruiterId
        - email
        - fullName
      properties:
        recruiterId:
          type: string
          description: >-
            Use this ID to filter requests in the same environment and match
            section rows.
        email:
          type: string
          format: email
        fullName:
          type: string
    AnalyticsMetadataDto:
      type: object
      required:
        - organizationId
        - requestedAt
        - filters
      properties:
        organizationId:
          type: string
          description: Organization identified by the API key, including in sandbox.
        requestedAt:
          type: string
          format: date-time
          description: UTC timestamp when this request started.
        filters:
          $ref: '#/components/schemas/AnalyticsFiltersDto'
    AnalyticsSectionsDto:
      type: object
      description: >-
        Only requested sections are present. Allow additional section and metric
        keys.
      properties:
        usage:
          $ref: '#/components/schemas/AnalyticsUsageSectionDto'
        activity:
          $ref: '#/components/schemas/AnalyticsActivitySectionDto'
        engagement:
          $ref: '#/components/schemas/AnalyticsEngagementSectionDto'
        recruiterSummary:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsRecruiterSummaryDto'
          description: >-
            All selected recruiters, including zeros, ordered by activeDays
            descending then ID.
    AnalyticsFiltersDto:
      type: object
      description: Resolved filters and inclusive UTC boundaries.
      required:
        - recruiterIds
        - breakdown
        - range
        - from
        - to
        - sections
      properties:
        recruiterIds:
          type: array
          items:
            type: string
          description: >-
            Deduplicated filter; empty means everyone. See recruiters for
            effective identities.
        breakdown:
          type: string
          enum:
            - DAILY
            - WEEKLY
            - MONTHLY
            - YEARLY
        range:
          type: string
          enum:
            - LAST_7_DAYS
            - LAST_30_DAYS
            - THIS_MONTH
            - LAST_MONTH
            - THIS_YEAR
            - LAST_YEAR
            - CUSTOM
        from:
          type: string
          format: date-time
          description: Inclusive start boundary at 00:00:00.000Z.
        to:
          type: string
          format: date-time
          description: Inclusive end boundary at 23:59:59.999Z.
        sections:
          type: array
          items:
            type: string
            enum:
              - usage
              - activity
              - engagement
              - recruiterSummary
          description: Selected sections after deduplication.
    AnalyticsUsageSectionDto:
      type: object
      description: Event counts, not active days. Sandbox returns synthetic counts.
      required:
        - profileViews
        - sherlockQueries
        - searchQueries
        - postedJobs
        - applications
        - sentMessages
        - contactTracking
      properties:
        profileViews:
          description: Tracked profile view/click events, not unique profiles.
          allOf:
            - $ref: '#/components/schemas/AnalyticsUsageMetricDto'
        sherlockQueries:
          description: Regular and legacy Sherlock runs; excludes API mode.
          allOf:
            - $ref: '#/components/schemas/AnalyticsUsageMetricDto'
        searchQueries:
          description: First-page, non-default searches; excludes COPILOT searches.
          allOf:
            - $ref: '#/components/schemas/AnalyticsUsageMetricDto'
        postedJobs:
          description: >-
            Jobs created in the range; excludes sandbox and Teamtailor, Flatchr,
            or Kombo imports.
          allOf:
            - $ref: '#/components/schemas/AnalyticsUsageMetricDto'
        applications:
          description: >-
            Acceptance events on currently shortlisted opportunities for
            selected recruiters’ non-sandbox jobs. ATS imports can count. No
            byRecruiter field.
          allOf:
            - $ref: '#/components/schemas/AnalyticsAggregateUsageMetricDto'
        sentMessages:
          description: Tracked search-message events.
          allOf:
            - $ref: '#/components/schemas/AnalyticsUsageMetricDto'
        contactTracking:
          description: >-
            LinkedIn clicks and direct contact-details views; excludes in-app
            events.
          allOf:
            - $ref: '#/components/schemas/AnalyticsUsageMetricDto'
    AnalyticsActivitySectionDto:
      type: object
      description: >-
        Distinct active UTC days per feature, including every selected
        recruiter.
      required:
        - sherlockQueries
        - searchQueries
        - postedJobs
        - sentMessages
      properties:
        sherlockQueries:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsRecruiterActivityDto'
        searchQueries:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsRecruiterActivityDto'
        postedJobs:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsRecruiterActivityDto'
        sentMessages:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsRecruiterActivityDto'
    AnalyticsEngagementSectionDto:
      type: object
      description: >-
        Every selected recruiter belongs to one group, based on average active
        days per week.
      required:
        - powerUsers
        - regularUsers
        - casualUsers
      properties:
        powerUsers:
          description: At least 2 active days/week.
          allOf:
            - $ref: '#/components/schemas/AnalyticsEngagementGroupDto'
        regularUsers:
          description: At least 1 and fewer than 2 active days/week.
          allOf:
            - $ref: '#/components/schemas/AnalyticsEngagementGroupDto'
        casualUsers:
          description: Fewer than 1 active day/week.
          allOf:
            - $ref: '#/components/schemas/AnalyticsEngagementGroupDto'
    AnalyticsRecruiterSummaryDto:
      type: object
      required:
        - recruiterId
        - sherlockQueries
        - searchQueries
        - postedJobs
        - sentMessages
        - activeDays
      properties:
        recruiterId:
          type: string
          description: Matches an ID in recruiters.
        sherlockQueries:
          type: number
          description: Sherlock event count.
        searchQueries:
          type: number
          description: Search event count.
        postedJobs:
          type: number
          description: Posted-job count.
        sentMessages:
          type: number
          description: Tracked search-message count.
        activeDays:
          type: number
          description: >-
            Distinct active UTC dates across these four features; each date
            counts once.
    AnalyticsUsageMetricDto:
      type: object
      description: Event totals, time series, and recruiter counts.
      required:
        - total
        - timeSeries
        - byRecruiter
      properties:
        total:
          type: number
          description: Events in the date range.
        timeSeries:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsTimeSeriesPointDto'
          description: Chronological UTC periods, including zeros.
        byRecruiter:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsRecruiterCountDto'
          description: >-
            All selected recruiters, including zeros, ordered by total
            descending then ID.
    AnalyticsAggregateUsageMetricDto:
      type: object
      description: Aggregate event counts. Applications omit byRecruiter.
      required:
        - total
        - timeSeries
      properties:
        total:
          type: number
          description: Events in the date range.
        timeSeries:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsTimeSeriesPointDto'
          description: Chronological UTC periods, including zeros.
    AnalyticsRecruiterActivityDto:
      type: object
      required:
        - recruiterId
        - activeDays
      properties:
        recruiterId:
          type: string
          description: Matches an ID in recruiters.
        activeDays:
          type: number
          description: Distinct active UTC dates; multiple events on a date count once.
    AnalyticsEngagementGroupDto:
      type: object
      required:
        - count
        - recruiters
      properties:
        count:
          type: number
          description: Number of recruiters in this group.
        recruiters:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsRecruiterEngagementDto'
          description: Ordered by averageActiveDaysPerWeek descending then ID.
    AnalyticsTimeSeriesPointDto:
      type: object
      required:
        - date
        - total
      properties:
        date:
          type: string
          format: date-time
          description: >-
            UTC period start. A partial first period can start before
            filters.from.
        total:
          type: number
          description: Events inside this period and the requested range; zero if none.
    AnalyticsRecruiterCountDto:
      type: object
      required:
        - recruiterId
        - total
      properties:
        recruiterId:
          type: string
          description: Matches an ID in recruiters.
        total:
          type: number
          description: Event count, including zero.
    AnalyticsRecruiterEngagementDto:
      type: object
      required:
        - recruiterId
        - activeDays
        - averageActiveDaysPerWeek
      properties:
        recruiterId:
          type: string
          description: Matches an ID in recruiters.
        activeDays:
          type: number
          description: >-
            Distinct UTC dates across Sherlock, searches, jobs, and messages;
            each date counts once.
        averageActiveDaysPerWeek:
          type: number
          description: >-
            activeDays divided by fractional weeks from the later of range start
            or account creation to range end, with a one-week minimum. Sandbox
            uses range start.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Your organization API key, available in [Organisation
        settings](https://app.collective.work/recruiter/organization/api).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.