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

# Trigger compounding job

> Triggers an on-demand compounding intelligence job for the workspace. Use after onboarding, file scanning, or bulk context ingestion to run intelligence pipelines immediately instead of waiting for the next scheduled cron cycle. Supported job types: consolidation (merge near-duplicate insights), pattern_detection (discover recurring patterns), playbook_synthesis (generate playbook rules from patterns), decay_sweep (reduce confidence on stale insights), and metrics (snapshot pipeline metrics). This endpoint is asynchronous and returns a job_run_id you can poll for status.

<Note>
  This endpoint requires the `record.write` scope on your API key.
</Note>

## Overview

Triggers an on-demand compounding intelligence job for your workspace. Use this after onboarding, file scanning, or bulk context ingestion to run intelligence pipelines immediately instead of waiting for the next scheduled cron cycle.

This endpoint is asynchronous. It returns `202 Accepted` immediately with a `job_run_id`, then the compounding job continues in the background.

## Job Types

| Job Type             | Description                                                                       |
| -------------------- | --------------------------------------------------------------------------------- |
| `consolidation`      | Merge near-duplicate insights that refer to the same underlying fact              |
| `pattern_detection`  | Discover recurring patterns across insights                                       |
| `playbook_synthesis` | Synthesize reusable action rules from detected patterns                           |
| `decay_sweep`        | Reduce confidence scores on stale insights that have not been reinforced recently |
| `metrics`            | Snapshot compounding pipeline metrics for the workspace                           |

## Dry Run

Set `dry_run` to `true` to preview what the job would do without persisting changes once the background run executes.

## Polling Job Status

After calling this endpoint, poll [Get compounding job status](/api-reference/compounding/get-job-status) with the returned `job_run_id` until the status changes from `accepted` or `running` to `completed` or `failed`.

Typical lifecycle:

* `accepted`: the API accepted the trigger request
* `running`: the background compounding worker has started
* `completed`: the job finished and final counts are available
* `failed`: the job failed and `error_details` explains why

## Example

```bash theme={null}
curl -X POST "https://app.nex.ai/api/developers/v1/compounding/trigger" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_type": "pattern_detection", "dry_run": false}'
```

```json theme={null}
{
  "job_run_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "pattern_detection",
  "workspace_id": 12345,
  "dry_run": false,
  "status": "accepted",
  "success": true
}
```


## OpenAPI

````yaml post /v1/compounding/trigger
openapi: 3.0.0
info:
  description: >-
    REST API for accessing and managing your Nex data. Generate API keys from
    the Nex web UI and use them to authenticate requests.
  title: Nex Developer API
  contact: {}
  version: '1.0'
servers:
  - url: https://app.nex.ai/api/developers
security: []
paths:
  /v1/compounding/trigger:
    post:
      tags:
        - Compounding
      summary: Trigger compounding job
      description: >-
        Triggers an on-demand compounding intelligence job for the workspace.
        Use after onboarding, file scanning, or bulk context ingestion to run
        intelligence pipelines immediately instead of waiting for the next
        scheduled cron cycle. Supported job types: consolidation (merge
        near-duplicate insights), pattern_detection (discover recurring
        patterns), playbook_synthesis (generate playbook rules from patterns),
        decay_sweep (reduce confidence on stale insights), and metrics (snapshot
        pipeline metrics). This endpoint is asynchronous and returns a
        job_run_id you can poll for status.
      operationId: triggerCompoundingJob
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/compounding.TriggerJobRequest'
        description: Job trigger request
        required: true
      responses:
        '202':
          description: Job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/compounding.TriggerJobResponse'
        '400':
          description: Bad request - Invalid job type or request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    compounding.TriggerJobRequest:
      type: object
      required:
        - job_type
      properties:
        job_type:
          type: string
          description: The type of compounding job to run
          enum:
            - consolidation
            - pattern_detection
            - playbook_synthesis
            - decay_sweep
            - metrics
        dry_run:
          type: boolean
          description: If true, preview impact without persisting changes
          default: false
    compounding.TriggerJobResponse:
      type: object
      properties:
        job_run_id:
          type: string
          format: uuid
          description: Unique identifier for this job execution
        job_type:
          type: string
          description: The type of job that was executed
          enum:
            - consolidation
            - pattern_detection
            - playbook_synthesis
            - decay_sweep
            - metrics
        workspace_id:
          type: integer
          description: Workspace ID the job ran against
        dry_run:
          type: boolean
          description: Whether the job ran in dry-run mode
        status:
          type: string
          description: Current job status
          enum:
            - accepted
        success:
          type: boolean
          description: Whether the job was accepted successfully
    httpx.APIError:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  securitySchemes:
    ApiKeyAuth:
      description: 'API key for authentication (format: "Bearer YOUR_API_KEY")'
      type: apiKey
      name: Authorization
      in: header

````