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

# List Agent's Jobs

> Retrieve a list of jobs for a specific agent or create a new job

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.roe-ai.com/v1/agents/YOUR_AGENT_ID/jobs/?organization_id=YOUR_ORG_ID" \
    --header "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>


## OpenAPI

````yaml GET /v1/agents/{agent_id}/jobs/
openapi: 3.1.0
info:
  title: Roe API
  version: 1.0.0
  description: Complete API documentation for Roe platform
servers:
  - url: https://api.roe-ai.com
    description: Production API
security: []
paths:
  /v1/agents/{agent_id}/jobs/:
    get:
      tags:
        - v1
      summary: List agent jobs or create a new agent job.
      description: Retrieve a list of jobs for a specific agent or create a new job
      operationId: v1_agents_jobs_list
      parameters:
        - in: path
          name: agent_id
          schema:
            type: string
            format: uuid
          required: true
        - in: query
          name: created_from
          schema:
            type: string
            format: date-time
        - in: query
          name: created_to
          schema:
            type: string
            format: date-time
        - in: query
          name: exclude_metadata
          schema:
            type: string
        - in: query
          name: job_id
          schema:
            type: string
        - in: query
          name: job_inputs
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: >-
            Maximum number of most-recent jobs to consider and count. Caps the
            reported total so pagination stays fast for agents with large job
            histories. Defaults to 100000; pass 0 for no cap (full count,
            slower).
          schema:
            type: integer
            default: 100000
            minimum: 0
            maximum: 1000000
        - in: query
          name: metadata
          schema:
            type: string
        - in: query
          name: ordering
          schema:
            type: array
            items:
              type: string
              enum:
                - '-agent_version_name'
                - '-cost'
                - '-created_at'
                - '-duration'
                - '-grader_score'
                - '-id'
                - '-last_updated_at'
                - '-status_code'
                - agent_version_name
                - cost
                - created_at
                - duration
                - grader_score
                - id
                - last_updated_at
                - status_code
          description: |-
            Ordering

            * `id` - Job ID
            * `-id` - Job ID (descending)
            * `agent_version_name` - Version
            * `-agent_version_name` - Version (descending)
            * `status_code` - Status
            * `-status_code` - Status (descending)
            * `created_at` - Created At
            * `-created_at` - Created At (descending)
            * `last_updated_at` - Last Updated At
            * `-last_updated_at` - Last Updated At (descending)
            * `cost` - Cost
            * `-cost` - Cost (descending)
            * `duration` - Time Elapsed
            * `-duration` - Time Elapsed (descending)
            * `grader_score` - Score
            * `-grader_score` - Score (descending)
          explode: false
          style: form
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
        - in: query
          name: search
          schema:
            type: string
        - in: query
          name: semantic_string
          schema:
            type: string
          description: Semantic search string for finding similar jobs using embeddings
        - in: query
          name: status_code
          schema:
            type: string
        - in: query
          name: verdict
          schema:
            type: string
        - in: query
          name: version_name
          schema:
            type: string
        - name: organization_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: >-
            Organization ID. This is required for access control. It can be
            provided via query or request body depending on the endpoint.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedListAgentJobList'
          description: Successfully retrieved paginated list of agent jobs.
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  oneOf:
                    - type: array
                      items:
                        type: string
                    - type: string
                description: >-
                  Validation failure: a map of field name to a list of error
                  messages (DRF serializers) or a single message (e.g.
                  organization_id validation).
          description: Invalid filter parameters.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetailResponse'
          description: >-
            Access to the Agents feature is forbidden or permission to access
            this agent denied.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetailResponse'
          description: Invalid page requested.
      security:
        - apiKeyAuth: []
components:
  schemas:
    PaginatedListAgentJobList:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/ListAgentJob'
    ErrorDetailResponse:
      type: object
      description: 'DRF default error body: NotFound, PermissionDenied, Http404, etc.'
      properties:
        detail:
          type: string
          description: Human-readable error detail
      required:
        - detail
    ListAgentJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        agent_version_name:
          type: string
          readOnly: true
        status_events:
          type: array
          items:
            $ref: '#/components/schemas/AgentJobStatusEvent'
        status_code:
          type: integer
          description: >-
            Current status code of the job (0=PENDING, 1=STARTED, 2=RETRY,
            3=SUCCESS, 4=FAILURE, 5=CANCELLED, 6=CACHED)
        created_at:
          type: string
          format: date-time
          description: When the job was created
        last_updated_at:
          type: string
          format: date-time
          readOnly: true
        duration_ms:
          type:
            - integer
            - 'null'
          readOnly: true
          description: >-
            Job duration in milliseconds, computed from status_events. End time
            is the last non-CACHED event so trailing cache hits don't inflate
            duration. Null while the job is still running or when timestamps are
            missing.
        job_inputs:
          type: array
          items:
            $ref: '#/components/schemas/JobInput'
          description: List of input data provided to the agent job
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Key-value pairs of metadata associated with the job
        ui_fields:
          readOnly: true
          description: >-
            Denormalized fields from agent output for list/metrics without
            loading S3 
        evaluation:
          oneOf:
            - $ref: '#/components/schemas/AgentJobEvaluation'
            - type: 'null'
          readOnly: true
        feedback_review:
          oneOf:
            - $ref: '#/components/schemas/AgentJobFeedbackNested'
            - type: 'null'
          readOnly: true
        creator:
          oneOf:
            - $ref: '#/components/schemas/UserInfo'
            - type: 'null'
          readOnly: true
      required:
        - agent_version_name
        - created_at
        - creator
        - duration_ms
        - evaluation
        - feedback_review
        - id
        - last_updated_at
        - status_code
        - status_events
        - ui_fields
    AgentJobStatusEvent:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        status_code:
          type: integer
        error_message:
          type: string
        error_details:
          type: object
          additionalProperties: {}
          description: Error details as key-value pairs
        count:
          type: integer
      required:
        - status_code
        - timestamp
    JobInput:
      type: object
      description: Serializer for individual job input data
      properties:
        key:
          type: string
          description: The input key
        description:
          type: string
          description: Description of the input
        data_type:
          type: string
          description: The data type of the input
        value:
          type: string
          description: The input value
        file_name:
          type: string
          description: File name if this input is a file
      required:
        - data_type
        - description
        - key
        - value
    AgentJobEvaluation:
      type: object
      properties:
        reference:
          oneOf:
            - {}
            - type: 'null'
        human_score:
          type:
            - number
            - 'null'
          format: double
        grader_score:
          type:
            - number
            - 'null'
          format: double
        feedback:
          type: string
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
      required:
        - created_at
        - updated_at
    AgentJobFeedbackNested:
      type: object
      properties:
        review_status:
          allOf:
            - $ref: '#/components/schemas/ReviewStatusEnum'
          description: |-
            Current review status of this job

            * `pending` - Pending Review
            * `approved` - Approved
            * `rejected` - Rejected
        corrected_verdict:
          type:
            - string
            - 'null'
          description: Human-selected correct verdict when they disagree with agent
        review_comment:
          type: string
          description: Reviewer's comment explaining their decision
        reviewed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp when the review was completed
        reviewed_by:
          type:
            - string
            - 'null'
          readOnly: true
      required:
        - reviewed_by
    UserInfo:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        email:
          type: string
          format: email
          title: Email address
          maxLength: 254
        first_name:
          type: string
          maxLength: 150
        last_name:
          type: string
          maxLength: 150
        display_name:
          type: string
          readOnly: true
      required:
        - display_name
        - email
        - id
    ReviewStatusEnum:
      enum:
        - pending
        - approved
        - rejected
      type: string
      description: |-
        * `pending` - Pending Review
        * `approved` - Approved
        * `rejected` - Rejected
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Organization API key passed as a Bearer token. This is the scheme used
        by the public SDK surface.

````