---
title: "Request a job"
method: POST
path: "/api/v4/jobs/request"
tags: ["jobs"]
---

# Request a job

`POST /api/v4/jobs/request`

## Request

- Base URL: `https://gitlab.com`
- URL: `https://gitlab.com/api/v4/jobs/request`
- Auth: none declared

Requests a job for a runner to execute.

## Request body

- PostApiV4JobsRequest: Request a job
  - `token` string, required: Runner's authentication token
  - `system_id` string: Runner's system identifier
  - `last_update` string: Runner's queue last_update token
  - `info` object: Runner's metadata
    - `name` string: Runner's name
    - `version` string: Runner's version
    - `revision` string: Runner's revision
    - `platform` string: Runner's platform
    - `architecture` string: Runner's architecture
    - `executor` string: Runner's executor
    - `features` object: Runner's features
    - `config` object: Runner's config
      - `gpus` string: GPUs enabled
    - `labels` object: Runner's labels
  - `session` object: Runner's session data
    - `url` string: Session's url
    - `certificate` string: Session's certificate
    - `authorization` string: Session's authorization

## Response `201`

Job was scheduled

- APIEntitiesCiJobRequestResponse: API_Entities_Ci_JobRequest_Response model
  - `id` string, required
  - `token` string, required
  - `allow_git_fetch` string, required
  - `job_info` APIEntitiesCiJobRequestJobInfo, required
    - `id` string, required
    - `name` string, required
    - `stage` string, required
    - `pipeline_id` string, required
    - `project_id` string, required
    - `project_name` string, required
    - `project_full_path` string, required
    - `namespace_id` string, required
    - `root_namespace_id` string, required
    - `organization_id` string, required
    - `instance_id` string, required
    - `instance_uuid` string, required
    - `user_id` string, required
    - `scoped_user_id` string, required
    - `time_in_queue_seconds` string, required
    - `project_jobs_running_on_instance_runners_count` string, required
    - `queue_size` string, required
    - `queue_depth` string, required
  - `git_info` APIEntitiesCiJobRequestGitInfo, required
    - `repo_url` string, required
    - `ref` string, required
    - `sha` string, required
    - `before_sha` string, required
    - `ref_type` string, required
    - `refspecs` string, required
    - `depth` string, required
    - `repo_object_format` string, required
    - `protected` string, required
  - `runner_info` APIEntitiesCiJobRequestRunnerInfo, required
    - `uuid` string, required
    - `timeout` string, required
    - `runner_session_url` string, required
  - `inputs` string, required
  - `variables` string, required
  - `steps` APIEntitiesCiJobRequestStep
    - `name` string, required
    - `script` string, required
    - `timeout` string, required
    - `when` string, required
    - `allow_failure` string, required
  - `hooks` APIEntitiesCiJobRequestHook, required
    - `name` string, required
    - `script` string, required
  - `image` APIEntitiesCiJobRequestImage, required
    - `name` string, required
    - `entrypoint` string, required
    - `ports` APIEntitiesCiJobRequestPort, required
      - `number` string, required
      - `protocol` string, required
      - `name` string, required
    - `executor_opts` string, required
    - `pull_policy` string, required
  - `services` APIEntitiesCiJobRequestService, required
    - `name` string, required
    - `entrypoint` string, required
    - `ports` APIEntitiesCiJobRequestPort, required
      - `number` string, required
      - `protocol` string, required
      - `name` string, required
    - `executor_opts` string, required
    - `pull_policy` string, required
    - `alias` string, required
    - `command` string, required
    - `variables` string, required
  - `artifacts` APIEntitiesCiJobRequestArtifacts, required
    - `name` string, required
    - `untracked` string
    - `paths` string, required
    - `exclude` string
    - `when` string, required
    - `expire_in` string, required
    - `artifact_type` string, required
    - `artifact_format` string, required
  - `cache` APIEntitiesCiJobRequestCache, required
    - `key` string, required
    - `untracked` string, required
    - `paths` string, required
    - `policy` string, required
    - `when` string, required
    - `fallback_keys` string, required
  - `credentials` APIEntitiesCiJobRequestCredentials, required
    - `type` string, required
    - `url` string, required
    - `username` string, required
    - `password` string, required
  - `features` string, required
  - `dependencies` string, required
  - `run` string
  - `suspend_options` string
  - `secrets` string
  - `policy_options` string

## Other responses

- `204`: No job for Runner
- `403`: Forbidden
- `409`: Conflict
- `422`: Runner is orphaned
- `429`: Too Many Requests

---

[API](https://skmtc.dev/gitlab/apis/gitlab-api.md) - [All operations](https://skmtc.dev/gitlab/apis/gitlab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitlab/apis/gitlab-api/revisions/b234947ef3f2?raw)