Arthur AI Jobs V1 API

openapi: 3.1.0
info:
  title: Arthur Scope Agents V1 Jobs V1 API
  version: 0.1.0
tags:
- name: Jobs V1
paths:
  /api/v1/jobs/{job_id}:
    get:
      tags:
      - Jobs V1
      summary: Get Job By Id
      description: Returns a single job by ID. Requires project_job_read permission.
      operationId: get_job
      security:
      - OAuth2AuthorizationCode:
        - project_job_read
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Jobs V1
      summary: Update Job By Id
      description: Updates a single job by ID. Requires project_job_update permission.
      operationId: update_job
      security:
      - OAuth2AuthorizationCode:
        - project_job_update
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchJob'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/jobs/{job_id}/state:
    put:
      tags:
      - Jobs V1
      summary: Update Job State
      description: Update job state. Requires project_job_put_state permission.
      operationId: put_job_state
      security:
      - OAuth2AuthorizationCode:
        - project_job_put_state
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: job_run_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
          description: Job run ID associated with the state update.
          title: Job Run Id
        description: Job run ID associated with the state update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutJobState'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/jobs/{job_id}/runs:
    get:
      tags:
      - Jobs V1
      summary: Get Job Runs
      description: Get Job runs. Required project_job_read_runs permission.
      operationId: get_job_runs
      security:
      - OAuth2AuthorizationCode:
        - project_job_read_runs
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList_JobRun_'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/jobs/{job_id}/runs/{job_run_id}/logs:
    post:
      tags:
      - Jobs V1
      summary: Append To Job Logs
      description: Append job logs. Requires project_job_append_logs permission.
      operationId: post_job_logs
      security:
      - OAuth2AuthorizationCode:
        - project_job_append_logs
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: job_run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: The job run associated with the logs. Should be formatted as a UUID.
          title: Job Run Id
        description: The job run associated with the logs. Should be formatted as a UUID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobLogs'
      responses:
        '204':
          description: Successful Response
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Jobs V1
      summary: Get Job Logs
      description: Get job logs for a run. Requires project_job_read_logs permission.
      operationId: get_job_logs
      security:
      - OAuth2AuthorizationCode:
        - project_job_read_logs
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: job_run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: The job run associated with the logs. Should be formatted as a UUID.
          title: Job Run Id
        description: The job run associated with the logs. Should be formatted as a UUID.
      - name: order
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrder'
          description: Override the sort order used. Optional.
          default: asc
        description: Override the sort order used. Optional.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList_JobLog_'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/jobs/{job_id}/runs/{job_run_id}/errors:
    post:
      tags:
      - Jobs V1
      summary: Append To Job Errors
      description: Append job errors. Requires project_job_append_errors permission.
      operationId: post_job_errors
      security:
      - OAuth2AuthorizationCode:
        - project_job_append_errors
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: job_run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: The job run associated with the errors. Should be formatted as a UUID.
          title: Job Run Id
        description: The job run associated with the errors. Should be formatted as a UUID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobErrors'
      responses:
        '204':
          description: Successful Response
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Jobs V1
      summary: Get Job Errors
      description: Get job errors. Requires project_job_read_errors permission.
      operationId: get_job_errors
      security:
      - OAuth2AuthorizationCode:
        - project_job_read_errors
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Job Id
      - name: job_run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: The job run associated with the errors. Should be formatted as a UUID.
          title: Job Run Id
        description: The job run associated with the errors. Should be formatted as a UUID.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList_JobError_'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/projects/{project_id}/jobs:
    get:
      tags:
      - Jobs V1
      summary: List Jobs
      description: 'Returns jobs in the project matching the filter and sorting criteria. If multiple filters are specified, results will only be returned that match all of the specified criteria. Requires project_list_jobs permission. Note: exclude_kinds takes precedence over kinds and will exclude jobs even if they are in kinds.'
      operationId: get_jobs
      security:
      - OAuth2AuthorizationCode:
        - project_list_jobs
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/JobsSort'
          description: Override the field used for sorting the returned list. Optional.
          default: queued_at
        description: Override the field used for sorting the returned list. Optional.
      - name: order
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrder'
          description: Override the sort order used. Optional.
          default: desc
        description: Override the sort order used. Optional.
      - name: duration_sec_greater_than
        in: query
        required: false
        schema:
          type: integer
          description: Filter the results for jobs that ran for greater than or equal to this number of seconds. Optional.
          title: Duration Sec Greater Than
        description: Filter the results for jobs that ran for greater than or equal to this number of seconds. Optional.
      - name: duration_sec_less_than
        in: query
        required: false
        schema:
          type: integer
          description: Filter the results for the jobs that ran for less than or equal to this number of seconds. Optional.
          title: Duration Sec Less Than
        description: Filter the results for the jobs that ran for less than or equal to this number of seconds. Optional.
      - name: started_before
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Filter the results for the jobs that started before this timestamp. Optional.
          title: Started Before
        description: Filter the results for the jobs that started before this timestamp. Optional.
      - name: started_after
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Filter the results for the jobs that started after this timestamp. Optional.
          title: Started After
        description: Filter the results for the jobs that started after this timestamp. Optional.
      - name: queued_before
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Filter the results for the jobs that were queued before this timestamp. Optional.
          title: Queued Before
        description: Filter the results for the jobs that were queued before this timestamp. Optional.
      - name: queued_after
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Filter the results for the jobs that were queued after this timestamp. Optional.
          title: Queued After
        description: Filter the results for the jobs that were queued after this timestamp. Optional.
      - name: ready_before
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Filter the results for the jobs that are ready before this timestamp. Optional.
          title: Ready Before
        description: Filter the results for the jobs that are ready before this timestamp. Optional.
      - name: ready_before_current_time
        in: query
        required: false
        schema:
          type: boolean
          description: When true, filters jobs ready before the current server time. Takes precedence over ready_before. Optional.
          default: false
          title: Ready Before Current Time
        description: When true, filters jobs ready before the current server time. Takes precedence over ready_before. Optional.
      - name: ready_after
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Filter the results for the jobs that are ready after this timestamp. Optional.
          title: Ready After
        description: Filter the results for the jobs that are ready after this timestamp. Optional.
      - name: ready_after_current_time
        in: query
        required: false
        schema:
          type: boolean
          description: When true, filters jobs ready after the current server time. Takes precedence over ready_after. Optional.
          default: false
          title: Ready After Current Time
        description: When true, filters jobs ready after the current server time. Takes precedence over ready_after. Optional.
      - name: finished_before
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Filter the results for the jobs that finished before this timestamp. Optional.
          title: Finished Before
        description: Filter the results for the jobs that finished before this timestamp. Optional.
      - name: finished_after
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Filter the results for the jobs that finished after this timestamp. Optional.
          title: Finished After
        description: Filter the results for the jobs that finished after this timestamp. Optional.
      - name: kinds
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/JobKind'
          description: Filter the results for the jobs of this kind. Optional.
          title: Kinds
        description: Filter the results for the jobs of this kind. Optional.
      - name: exclude_kinds
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/JobKind'
          description: Exclude jobs of these kinds. Takes precedence over kinds.
          title: Exclude Kinds
        description: Exclude jobs of these kinds. Takes precedence over kinds.
      - name: states
        in: query
        required: false
        schema:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/JobState'
          description: Filter the results for jobs in these states. Optional.
          title: States
        description: Filter the results for jobs in these states. Optional.
      - name: error_count_above
        in: query
        required: false
        schema:
          type: integer
          description: Filter the results for the jobs that had greater than or equal to this many errors. Optional.
          title: Error Count Above
        description: Filter the results for the jobs that had greater than or equal to this many errors. Optional.
      - name: data_plane_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
          description: Filter the results for the jobs that were ran on this dataplane. Optional.
          title: Data Plane Id
        description: Filter the results for the jobs that were ran on this dataplane. Optional.
      - name: schedule_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
          description: Filter the results for jobs associated with this schedule ID. Optional.
          title: Schedule Id
        description: Filter the results for jobs associated with this schedule ID. Optional.
      - name: trigger_type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/JobTrigger'
          description: Filter the results for the jobs that were started by this trigger type. Optional.
        description: Filter the results for the jobs that were started by this trigger type. Optional.
      - name: triggered_by_user_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
          description: Filter the results for the jobs that started by this user id. Only valid when trigger_type = 'user'. Optional.
          title: Triggered By User Id
        description: Filter the results for the jobs that started by this user id. Only valid when trigger_type = 'user'. Optional.
      - name: triggered_by_user_email
        in: query
        required: false
        schema:
          type: string
          description: Filter the results for the jobs that started by this user email. Only valid when trigger_type = 'user'. Optional.
          format: email
          title: Triggered By User Email
        description: Filter the results for the jobs that started by this user email. Only valid when trigger_type = 'user'. Optional.
      - name: model_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
          description: Filter the results for jobs associated with this model ID. Includes jobs associated with datasets used by the model. Optional.
          title: Model Id
        description: Filter the results for jobs associated with this model ID. Includes jobs associated with datasets used by the model. Optional.
      - name: nonce
        in: query
        required: false
        schema:
          type: string
          description: Filter the results for jobs that match a job nonce used to ensure exactly once execution.
          title: Nonce
        description: Filter the results for jobs that match a job nonce used to ensure exactly once execution.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: The page to return starting from 1 up to total_pages.
          default: 1
          title: Page
        description: The page to return starting from 1 up to total_pages.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          description: The number of records per page. The max is 1000.
          default: 20
          title: Page Size
        description: The number of records per page. The max is 1000.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfiniteResourceList_Job_'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Jobs V1
      summary: Submit Jobs Batch
      description: Submit new jobs to run. Requires project_create_job permission.
      operationId: post_submit_jobs_batch
      security:
      - OAuth2AuthorizationCode:
        - project_create_job
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostJobBatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobsBatch'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/data_planes/{data_plane_id}/jobs/next:
    post:
      tags:
      - Jobs V1
      summary: Dequeue Job
      description: Returns the next available job for processing from the data plane's job queue. Requires data_plane_jobs_dequeue_next permission.
      operationId: post_dequeue_job
      security:
      - OAuth2AuthorizationCode:
        - data_plane_jobs_dequeue_next
      parameters:
      - name: data_plane_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Data Plane Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobDequeueParameters'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobRun'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
        '204':
          description: No Content
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    InfinitePagination:
      properties:
        page:
          type: integer
          title: Page
          description: The current page number. Page 1 is the first page.
          default: 1
        page_size:
          type: integer
          title: Page Size
          description: Number of records per page.
          default: 20
      type: object
      title: InfinitePagination
    AgentMetadata:
      properties:
        provider:
          $ref: '#/components/schemas/RegisteredAgentProvider'
          description: Provider of the registered agent.
        gcp_metadata:
          anyOf:
          - $ref: '#/components/schemas/GCPAgentMetadata'
          - type: 'null'
          description: Metadata for the agent.
      type: object
      required:
      - provider
      title: AgentMetadata
    PostJobBatch:
      properties:
        jobs:
          items:
            $ref: '#/components/schemas/PostJob'
          type: array
          title: Jobs
          description: List of jobs to create.
      type: object
      required:
      - jobs
      title: PostJobBatch
    TestCustomAggregationJobSpec:
      properties:
        job_type:
          type: string
          const: test_custom_aggregation
          title: Job Type
          default: test_custom_aggregation
        test_custom_aggregation_id:
          type: string
          format: uuid
          title: Test Custom Aggregation Id
          description: The id of the custom aggregation test.
      type: object
      required:
      - test_custom_aggregation_id
      title: TestCustomAggregationJobSpec
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    User:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Time of record creation.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Time of last record update.
        organization_id:
          type: string
          format: uuid4
          title: Organization Id
          description: The ID of the Arthur organization the user belongs to.
        id:
          type: string
          format: uuid4
          title: Id
          description: Unique user ID assigned by Arthur.
        first_name:
          type: string
          title: First Name
          description: The user's first name.
        last_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Name
          description: The user's last name.
        email:
          anyOf:
          - type: string
            format: email
          - type: 'null'
          title: Email
          description: The user's email, if provided.
        picture:
          anyOf:
          - type: string
          - type: 'null'
          title: Picture
          description: A url to the user's profile picture, if one exists.
        user_type:
          $ref: '#/components/schemas/UserType'
          description: The type of user.
        data_plane_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Data Plane Id
          description: Arthur data plane ID. Only set for data plane users.
        client_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Client Id
          description: Arthur client ID for this user. Only set for service account type users.
        organization_name:
          type: string
          title: Organization Name
          description: Name of user's Arthur organization.
      type: object
      required:
      - created_at
      - updated_at
      - organization_id
      - id
      - first_name
      - last_name
      - user_type
      - organization_name
      title: User
    DataResultFilterOp:
      type: string
      enum:
      - greater_than
      - less_than
      - equals
      - not_equals
      - greater_than_or_equal
      - less_than_or_equal
      - in
      - not_in
      title: DataResultFilterOp
    PatchJob:
      properties:
        max_attempts:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Attempts
          description: Max number of times the job can fail and be retried. Adjusting this number will only affect jobs in the Queued or Running states. Jobs in the Failed state will not be retried further by adjusting this number.
      type: object
      required:
      - max_attempts
      title: PatchJob
    ConnectorPaginationOptions:
      properties:
        page:
          type: integer
          minimum: 1.0
          title: Page
          default: 1
        page_size:
          type: integer
          maximum: 500.0
          minimum: 1.0
          title: Page Size
          default: 25
      type: object
      title: ConnectorPaginationOptions
    JobsSort:
      type: string
      enum:
      - queued_at
      - started_at
      - finished_at
      title: JobsSort
    NewMetricRequest:
      properties:
        type:
          $ref: '#/components/schemas/MetricType'
          description: Type of the metric. It can only be one of QueryRelevance, ResponseRelevance, ToolSelection
          examples:
          - UserQueryRelevance
        name:
      

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arthur-ai/refs/heads/main/openapi/arthur-ai-jobs-v1-api-openapi.yml