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

# Trigger a managed-agent run

> Queues or reuses a manual run through the existing flag, credit metering, model-catalog, idempotency, and autonomy controls. This endpoint has a stricter rate limit than read endpoints.



## OpenAPI

````yaml /openapi.json post /projects/{projectId}/agents/{agentKey}/runs
openapi: 3.1.0
info:
  title: DevTune API
  version: 2.0.0
  description: >-
    API for programmatic access to your AI visibility data, webhook
    subscriptions, and automation workflows. Use this API to integrate DevTune
    data into CI/CD pipelines, BI tools, AI agents, and operational systems.
servers:
  - url: https://devtune.ai/api/v2
    description: Production
security:
  - bearerAuth: []
paths:
  /projects/{projectId}/agents/{agentKey}/runs:
    post:
      summary: Trigger a managed-agent run
      description: >-
        Queues or reuses a manual run through the existing flag, credit
        metering, model-catalog, idempotency, and autonomy controls. This
        endpoint has a stricter rate limit than read endpoints.
      operationId: triggerManagedAgentRun
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: agentKey
          in: path
          required: true
          description: Roster or custom agent key.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                instructions:
                  type: string
                  minLength: 1
                  maxLength: 4000
                modelId:
                  type: string
                  minLength: 1
                  maxLength: 120
                requestIdempotencyKey:
                  type: string
                  format: uuid
              required:
                - requestIdempotencyKey
      responses:
        '200':
          description: Queued or reused managed-agent run
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentRunTriggerResult'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - data
                  - meta
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          description: Insufficient included or purchased credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/RateLimitExceededError'
components:
  schemas:
    AgentRunTriggerResult:
      type: object
      properties:
        attribution:
          type: object
          properties:
            actorType:
              type: string
              enum:
                - key_minting_user
                - service
            apiKeyId:
              type: string
              format: uuid
            createdByUserId:
              type:
                - string
                - 'null'
              format: uuid
            source:
              type: string
              enum:
                - api_key
          required:
            - actorType
            - apiKeyId
            - createdByUserId
            - source
        status:
          type: string
          enum:
            - already_queued
            - failed
            - queued
          description: >-
            Dispatch outcome. already_queued is returned only for an idempotent
            replay resolved through this request's idempotency key; an unrelated
            queued run returns 409.
        taskId:
          type: string
          format: uuid
        workflowId:
          type: string
          format: uuid
          description: >-
            Pinned workflow revision ID. Present when status is queued or
            failed; absent for already_queued idempotent replays resolved
            through the caller's request key.
      required:
        - attribution
        - status
        - taskId
    Meta:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        projectId:
          type: string
          format: uuid
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        status:
          type: integer
      required:
        - error
        - message
        - status
  responses:
    BadRequestError:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFoundError:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ConflictError:
      description: Request conflicts with current resource state
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimitExceededError:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    X-RateLimit-Limit:
      description: Maximum requests per window
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests remaining in current window
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix timestamp when the window resets
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key with dtk_live_ prefix. Obtain it from API Keys in the account
        sidebar. New keys start with all supported scopes selected for the
        chosen project, and you can narrow them to specific read/write scopes as
        needed.

````