> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Generate an activity & stage-change report > Aggregates recruiter activity, candidate sourcing, pipeline stage changes, campaign enrollments, and tasks for the requested date window. Group by recruiter, job, or company. Mirrors the in-app "Generate report" surface and is the recommended way to produce daily / weekly / monthly performance reports. **Date filter**: applies to `created_at` for activities / candidates / tasks, `entered_at` for stage changes, and `enrolled_at` for campaign enrollments. **Optional sections** via `include`: - `pipeline_snapshot` — current candidate count per pipeline stage (job/company segments only). - `job_breakdown` — per-job candidates-sourced breakdown for each recruiter (team_member segments only). - `crm_activities` — fold `client_activities` + `client_status_changes` into the company segment metrics. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/activity-reports openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/activity-reports: post: tags: - Activity Reports summary: Generate an activity & stage-change report description: >- Aggregates recruiter activity, candidate sourcing, pipeline stage changes, campaign enrollments, and tasks for the requested date window. Group by recruiter, job, or company. Mirrors the in-app "Generate report" surface and is the recommended way to produce daily / weekly / monthly performance reports. **Date filter**: applies to `created_at` for activities / candidates / tasks, `entered_at` for stage changes, and `enrolled_at` for campaign enrollments. **Optional sections** via `include`: - `pipeline_snapshot` — current candidate count per pipeline stage (job/company segments only). - `job_breakdown` — per-job candidates-sourced breakdown for each recruiter (team_member segments only). - `crm_activities` — fold `client_activities` + `client_status_changes` into the company segment metrics. operationId: generateActivityReport requestBody: content: application/json: schema: $ref: '#/components/schemas/ActivityReportRequest' responses: '200': description: Activity report generated content: application/json: schema: $ref: '#/components/schemas/ActivityReportResponse' example: success: true data: segment_by: team_member period: weekly date_from: '2026-06-19T19:00:00Z' date_to: '2026-06-26T19:00:00Z' aggregate: activities_by_type: - type: campaign_enrollment label: Campaign Enrollments count: 18 - type: secondary_note label: Notes count: 12 - type: email label: Emails count: 8 - type: linkedin_message label: LinkedIn Messages count: 24 - type: call_note label: Call Note count: 4 candidates_sourced: 42 stage_changes: 21 rejections: 6 enrollments: 18 tasks: 9 stage_changes_by_stage: - pipeline_stage_id: 567e8901-e23c-45d6-e789-012345678901 stage_name: Sourced stage_color: '#94a3b8' global_order: 1 count: 12 - pipeline_stage_id: 678e9012-e34d-56f7-a890-123456789012 stage_name: Interview stage_color: '#facc15' global_order: 3 count: 9 pipeline_snapshot: - pipeline_stage_id: 567e8901-e23c-45d6-e789-012345678901 stage_name: Sourced stage_color: '#94a3b8' global_order: 1 candidate_count: 30 - pipeline_stage_id: 678e9012-e34d-56f7-a890-123456789012 stage_name: Interview stage_color: '#facc15' global_order: 3 candidate_count: 5 job_breakdown: - job_id: 345e6789-e01b-23c4-d567-890123456789 job_title: Senior Software Engineer company_id: 111e2222-e333-4444-e555-666666666666 company_name: Acme Corp candidates_sourced: 28 segments: - segment_type: team_member id: 234e5678-e90a-12b3-c456-789012345678 name: Jane Smith company_id: null company_name: null metrics: activities_by_type: - type: campaign_enrollment label: Campaign Enrollments count: 18 - type: secondary_note label: Notes count: 12 - type: email label: Emails count: 8 - type: linkedin_message label: LinkedIn Messages count: 24 - type: call_note label: Call Note count: 4 candidates_sourced: 42 stage_changes: 21 rejections: 6 enrollments: 18 tasks: 9 stage_changes_by_stage: - pipeline_stage_id: 567e8901-e23c-45d6-e789-012345678901 stage_name: Sourced stage_color: '#94a3b8' global_order: 1 count: 12 - pipeline_stage_id: 678e9012-e34d-56f7-a890-123456789012 stage_name: Interview stage_color: '#facc15' global_order: 3 count: 9 pipeline_snapshot: - pipeline_stage_id: 567e8901-e23c-45d6-e789-012345678901 stage_name: Sourced stage_color: '#94a3b8' global_order: 1 candidate_count: 30 - pipeline_stage_id: 678e9012-e34d-56f7-a890-123456789012 stage_name: Interview stage_color: '#facc15' global_order: 3 candidate_count: 5 job_breakdown: - job_id: 345e6789-e01b-23c4-d567-890123456789 job_title: Senior Software Engineer company_id: 111e2222-e333-4444-e555-666666666666 company_name: Acme Corp candidates_sourced: 28 '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: ActivityReportRequest: type: object properties: segment_by: type: string enum: - team_member - job - company description: |- Dimension to group the report by: - `team_member` — one segment per recruiter - `job` — one segment per job - `company` — one segment per client/organization company period: type: string enum: - daily - weekly - monthly - custom default: custom description: >- Convenience preset that derives the date range when `date_from` / `date_to` are omitted: - `daily` — the start of today through now - `weekly` — the trailing 7 days through now - `monthly` — the trailing 30 days through now - `custom` — use the explicit `date_from` / `date_to` values (required when `custom`). date_from: type: string format: date-time description: >- Start of the report window (ISO 8601). Required when `period=custom`. Applied to `created_at` for activities, candidates, tasks, and `entered_at` for stage changes / `enrolled_at` for campaign enrollments. Custom windows are limited to 2 years. date_to: type: string format: date-time description: >- End of the report window (ISO 8601). Required when `period=custom`. Custom windows are limited to 2 years. team_member_ids: type: array items: type: string format: uuid maxItems: 200 description: >- Optional recruiter UUIDs to narrow the report. Affects both the aggregate totals and per-segment rows. Maximum 200 IDs. Get IDs from `GET /v1/team-members`. job_ids: type: array items: type: string format: uuid maxItems: 200 description: >- Optional job UUIDs to narrow the report. Affects both the aggregate totals and per-segment rows. Maximum 200 IDs. organization_company_ids: type: array items: type: string format: uuid maxItems: 200 description: >- Optional client/company UUIDs to narrow the report. When provided, only activity tied to jobs at these companies (or directly to these client companies) is counted. Maximum 200 IDs. include: type: array items: type: string enum: - pipeline_snapshot - job_breakdown - crm_activities description: >- Optional sections to embed per segment. Values: - `pipeline_snapshot` — current candidate count per pipeline stage (for `job` / `company` segments) - `job_breakdown` — per-job candidates-sourced breakdown (for `team_member` segments) - `crm_activities` — fold `client_activities` and `client_status_changes` into the company segment metrics required: - segment_by ActivityReportResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/ActivityReportData' required: - success - data ActivityReportData: type: object properties: segment_by: type: string enum: - team_member - job - company description: Echo of the request `segment_by`. period: type: string enum: - daily - weekly - monthly - custom description: Echo of the request `period`. date_from: type: string description: >- Resolved start of the report window (ISO 8601). Computed from `period` when not supplied. date_to: type: string description: Resolved end of the report window (ISO 8601). aggregate: allOf: - $ref: '#/components/schemas/ActivityReportMetrics' - description: >- Totals across the entire selection (every segment combined). Useful as the report header. segments: type: array items: $ref: '#/components/schemas/ActivityReportSegment' description: >- Per-segment rows. Empty when the selection produced no activity in the window. required: - segment_by - period - date_from - date_to - aggregate - segments ActivityReportMetrics: type: object properties: activities_by_type: type: array items: $ref: '#/components/schemas/ActivityReportActivityCount' description: >- Activity counts grouped by `person_activities.type`. Excludes `candidate_summary` and `primary_note`. Includes a synthetic `campaign_enrollment` row when relevant. candidates_sourced: type: integer description: >- Number of `candidates` created in the window. For team-member segments this is filtered to `sourced_by_team_member = member`. stage_changes: type: integer description: >- Number of `candidate_pipeline_statuses` rows entered in the window (every pipeline move, including rejections). rejections: type: integer description: >- Subset of stage changes where `stage_change_reason_id` is set (i.e. the move was a rejection). enrollments: type: integer description: Campaign enrollments created in the window (`sequence_enrollments`). tasks: type: integer description: >- Tasks created in the window. For team-member segments this counts tasks the member owns (via `task_owners`). stage_changes_by_stage: type: array items: $ref: '#/components/schemas/ActivityReportStageChangeBreakdown' description: >- Per-stage breakdown of stage changes. Stages are keyed by the global `pipeline_stages.id` so the same logical stage collapses across jobs. pipeline_snapshot: type: array items: $ref: '#/components/schemas/ActivityReportPipelineSnapshotEntry' description: >- Current candidate distribution across pipeline stages (snapshot, not date-filtered). Only present for `job` / `company` segments when `include` contains `pipeline_snapshot`. job_breakdown: type: array items: $ref: '#/components/schemas/ActivityReportJobBreakdownEntry' description: >- Per-job sourcing breakdown for this segment. Only present for `team_member` segments when `include` contains `job_breakdown`. required: - activities_by_type - candidates_sourced - stage_changes - rejections - enrollments - tasks - stage_changes_by_stage ActivityReportSegment: type: object properties: segment_type: type: string enum: - team_member - job - company description: Echoes the request `segment_by` so each row is self-describing. id: type: string format: uuid description: >- Identity of the segment — team_member.id, jobs.id, or organization_companies.id depending on `segment_type`. name: type: string description: >- Display name — "First Last" for team members, the job title for jobs, or the company name for companies. company_id: type: - string - 'null' format: uuid description: >- For `job` segments: the client/company UUID linked to the job. Null for other segment types. company_name: type: - string - 'null' description: >- For `job` segments: the client/company display name. Null for other segment types. metrics: allOf: - $ref: '#/components/schemas/ActivityReportMetrics' - description: >- All activity counts and breakdowns for this segment in the window. required: - segment_type - id - name - company_id - company_name - metrics ActivityReportActivityCount: type: object properties: type: type: string description: >- Activity type key (e.g. `secondary_note`, `email`, `linkedin_message`, or a team-defined custom key). The synthetic key `campaign_enrollment` is used for the campaign enrollments rollup. label: type: string description: >- Human-friendly display label. Falls back to the team-configured `person_activity_types.name` then to a title-cased version of the key. count: type: integer description: Number of activities of this type in the window. required: - type - label - count ActivityReportStageChangeBreakdown: type: object properties: pipeline_stage_id: type: string format: uuid description: >- Global `pipeline_stages.id`. The same logical stage (e.g. "Interview") collapses across jobs onto a single row. stage_name: type: string description: Stage display name. stage_color: type: string description: Stage display color (hex). global_order: type: integer description: >- Position of this stage in the global pipeline ordering. Use to sort funnel rows. count: type: integer description: Number of stage changes into this stage in the window. required: - pipeline_stage_id - stage_name - stage_color - global_order - count ActivityReportPipelineSnapshotEntry: type: object properties: pipeline_stage_id: type: string format: uuid description: Global `pipeline_stages.id`. stage_name: type: string description: Stage display name. stage_color: type: string description: Stage display color (hex). global_order: type: integer description: Stage position in the global ordering. candidate_count: type: integer description: >- Current candidate count in this stage (snapshot — NOT filtered by date). required: - pipeline_stage_id - stage_name - stage_color - global_order - candidate_count ActivityReportJobBreakdownEntry: type: object properties: job_id: type: string format: uuid description: Job UUID. job_title: type: string description: Job title. company_id: type: - string - 'null' format: uuid description: Client/company UUID linked to the job. company_name: type: - string - 'null' description: Client/company display name. candidates_sourced: type: integer description: Candidates sourced into this job by the segment owner in the window. required: - job_id - job_title - company_id - company_name - candidates_sourced securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````