Skip to main content

Automation Runs

The automation/runs namespace provides API methods for automation runs and threads. You can use these methods to retrieve automation runs and threads for a project, create new runs and threads, submit test results (including custom fields, artifacts & links) and finally mark runs and threads as completed.

GET /automation/runs/{run_id}/tests

⚠️ NOTE: This endpoint is coming soon. 

It's planned for release alongside the upcoming CLI automation linking extension.

Returns a paginated list of test results for the specified automation run. Each result includes the repository_case_id of the linked repository test case if the automation case has been linked to one, or null otherwise.

This method uses pagination so you might need to request additional pages to retrieve all results.

run_id id required
ID of the automation run.
 

Request

Parameters
Schema

page integer
Number of page to return (default: first page).
 

per_page integer
Maximum number of test results to return per page (supported range: 100–1000; default: 100).
 

sort string
Sort field (supported: automation_run_tests:id, automation_run_tests:name, automation_run_tests:status, automation_run_tests:elapsed, automation_run_tests:created_at; default: automation_run_tests:id).
 

order string
Sort order (supported: asc, desc; default: desc).
 

thread_id integer
Filter results to a single automation run thread by thread ID.
 

status_id string
Comma-separated list of status IDs to filter by. Use: 1 for Neutral, 2 for Success, 3 for Failure, 4 for Running.
  

{
  "page": {
      "type": "integer",
      "format": "int64",
      "description": "Number of page to return (default: first page)."
  },
  "per_page": {
      "type": "integer",
      "format": "int64",
      "description": "Maximum number of test results to return per page (range: 100–1000; default: 100)."
  },
  "sort": {
      "type": "string",
      "enum": [
          "automation_run_tests:id",
          "automation_run_tests:name",
          "automation_run_tests:status",
          "automation_run_tests:elapsed",
          "automation_run_tests:created_at"
      ],
      "description": "Sort field for the list of test results."
  },
  "order": {
      "type": "string",
      "enum": ["asc", "desc"],
      "description": "Sort order (ascending or descending)."
  },
  "thread_id": {
      "type": "integer",
      "format": "int64",
      "description": "Filter results to a single automation run thread by thread ID."
  },
  "status_id": {
      "type": "string",
      "description": "Comma-separated list of status IDs to filter by. Use: 1 for Neutral, 2 for Success, 3 for Failure, 4 for Running."
  }
}

Response

GET /api/v1/automation/runs/1/tests

 
200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": null,
    "last_page": 1,
    "per_page": 100,
    "total": 4,
    "result": [
        {
            "automation_test_id": 101,
            "automation_case_id": 42,
            "repository_case_id": 17,
            "key": "com.example.LoginTest#testValidLogin",
            "name": "testValidLogin",
            "folder": "com.example.LoginTest",
            "status": "passed",
            "elapsed": 1250,
            "file": "LoginTest.java",
            "line": 34,
            "thread_id": 5,
            "created_at": "2025-09-24T10:05:22.000Z"
        },
        ..
    ]
}

Examples

// Filter test results to a single thread
GET /api/v1/automation/runs/1/tests?thread_id=5

// Filter by status (failures only)
GET /api/v1/automation/runs/1/tests?status_id=3

// Sort by elapsed time descending (slowest tests first)
GET /api/v1/automation/runs/1/tests?sort=automation_run_tests:elapsed&order=desc

// Paginate through a large run
GET /api/v1/automation/runs/1/tests?page=2&per_page=500

Status codes

200 401 403 404429 (details)

GET /projects/{project_id}/automation/runs

Returns all automation runs for a project.

This method uses pagination so you might need to request additional pages to retrieve all automation runs.

project_id id required
ID of the project.
 

Request

Parameters
Schema

page integer
Number of page to return (default: first page).
 

per_page integer
Maximum number of automation runs to return (supported: 15, 25, 50, 100; default: 100).
 

sort string
Sort field (supported: automation_runs:created_at; default: automation_runs:created_at).
 

order string
Sort order (supported: asc, desc; default: desc).
 

name string
Filter automation runs by name (partial match).
 

status string
Comma-separated list of statuses to filter by. Use: 2 for success, 3 for failure, 4 for running.
 

source_id string
Comma-separated list of automation source IDs to filter by.
 

milestone_id string
Comma-separated list of milestone IDs to filter by.
 

config_id string
Comma-separated list of configuration IDs to filter by.
 

tags string
Comma-separated list of tag names to filter by.
 

created_after string
Limit results to automation runs created after this date/time (ISO 8601, UTC).
 

created_before string
Limit results to automation runs created before this date/time (ISO 8601, UTC).
 

created_by string
Comma-separated list of user IDs to filter by creator.
 

expands string
Comma-separated list of expands to return.
  

{
  "page": {
      "type": "integer",
      "format": "int64",
      "description": "Number of page to return (default: first page)."
  },
  "per_page": {
      "type": "integer",
      "format": "int64",
      "enum": [15, 25, 50, 100],
      "description": "Maximum number of items to return per page (default: 100)."
  },
  "sort": {
      "type": "string",
      "enum": ["automation_runs:created_at"],
      "default": "automation_runs:created_at",
      "description": "Sort field for the list of automation runs."
  },
  "order": {
      "type": "string",
      "enum": ["asc", "desc"],
      "default": "desc",
      "description": "Sort order (ascending or descending)."
  },
  "name": {
      "type": "string",
      "description": "Filter automation runs by name (partial match)."
  },
  "status": {
      "type": "string",
      "description": "Comma-separated list of statuses to filter by. Use: 2 for success, 3 for failure, 4 for running."
  },
  "source_id": {
      "type": "string",
      "description": "Comma-separated list of automation source IDs to filter by."
  },
  "milestone_id": {
      "type": "string",
      "description": "Comma-separated list of milestone IDs to filter by."
  },
  "config_id": {
      "type": "string",
      "description": "Comma-separated list of configuration IDs to filter by."
  },
  "tags": {
      "type": "string",
      "description": "Comma-separated list of tag names to filter by."
  },
  "created_after": {
      "type": "string",
      "format": "date-time",
      "description": "Limit results to automation runs created after this date/time (ISO 8601, UTC)."
  },
  "created_before": {
      "type": "string",
      "format": "date-time",
      "description": "Limit results to automation runs created before this date/time (ISO 8601, UTC)."
  },
  "created_by": {
      "type": "string",
      "description": "Comma-separated list of user IDs to filter by creator."
  },
  "expands": {
      "type": "string",
      "description": "Comma-separated list of expands to return (automation_sources, configs, milestones, statuses, users)."
  }
}

This method supports the following expands so you can automatically include additional information for referenced objects:

  • automation_sources
  • configs
  • milestones
  • statuses
  • users

Response

GET /api/v1/projects/1/automation/runs

 
200 OK
{
    "page": 1,
    "prev_page": null,
    "next_page": 2,
    "last_page": 2,
    "per_page": 100,
    "total": 150,
    "result": [
        {
            "id": 1,
            "project_id": 1,
            "name": "Backend CI — main branch",
            "status": 2,
            ..
            "is_completed": true,
            "success_count": 90,
            "failure_count": 10,
            "completed_count": 100,
            "total_count": 100,
            "thread_count": 4,
            "thread_active_count": 0,
            "thread_completed_count": 4,
            "created_at": "2025-09-24T09:00:00.000000Z",
            "created_by": 2,
            "updated_at": null,
            "updated_by": null,
            "completed_at": "2025-09-24T09:12:30.000000Z",
            "completed_by": 2
        },
        ..
    ],
    "expands": {}
}

Examples

// Get all automation runs for a project
GET /api/v1/projects/1/automation/runs

// Filter by name (partial match)
GET /api/v1/projects/1/automation/runs?name=backend

// Get only failed runs
GET /api/v1/projects/1/automation/runs?status=3

// Filter by automation source
GET /api/v1/projects/1/automation/runs?source_id=2

// Filter by creation date
GET /api/v1/projects/1/automation/runs?created_after=2025-09-01T00:00:00Z

// Include source and user expands
GET /api/v1/projects/1/automation/runs?expands=automation_sources,users

// Paginate through results
GET /api/v1/projects/1/automation/runs?page=2

Status codes

200 401 403 422429 (details)

GET /automation/runs/{automation_run_id}

Returns a single automation run.

automation_run_id id required
ID of the automation run.
 

Request

Parameters
Schema

expands string
Comma-separated list of expands to return.
  

{
  "expands": {
      "type": "string",
      "description": "Comma-separated list of expands to return (automation_sources, configs, milestones, statuses, users)."
  }
}

This method supports the following expands so you can automatically include additional information for referenced objects:

  • automation_sources
  • configs
  • milestones
  • statuses
  • users

Response

GET /api/v1/automation/runs/1

 
200 OK
{
    "result": {
        "id": 1,
        "project_id": 1,
        "name": "Backend CI — main branch",
        "status": 2,
        ..
        "is_completed": true,
        "success_count": 90,
        "failure_count": 10,
        "completed_count": 100,
        "total_count": 100,
        "thread_count": 4,
        "thread_active_count": 0,
        "thread_completed_count": 4,
        "created_at": "2025-09-24T09:00:00.000000Z",
        "created_by": 2,
        "updated_at": null,
        "updated_by": null,
        "completed_at": "2025-09-24T09:12:30.000000Z",
        "completed_by": 2
    },
    "expands": {}
}

Examples

// Get automation run with ID 1
GET /api/v1/automation/runs/1

// Include source and user expands
GET /api/v1/automation/runs/1?expands=automation_sources,configs,users

Status codes

200 401 403 404429 (details)

POST /projects/{project_id}/automation/runs

Creates a new automation run in a target project in preparation for adding threads and test results.

project_id id required
ID of the target project.
 

Request

Parameters
Schema

name string required
Name of the new automation run.
 

source string required
Name of the source for the new automation run. If this source does not already exist in the target project, Testmo automatically creates a new one. It is recommended to keep source names short. Good examples are backend, frontend or mobile-iphone.
 

config string
Name of the configuration for the new automation run.
 

config_id id
ID of the configuration for the new automation run. If both config and config_id are specified, config_id is given precedence.
 

milestone string
Name of the milestone for the new automation run.
 

milestone_id id
ID of the milestone for the new automation run. If both milestone and milestone_id are specified, milestone_id is given precedence.
 

tags array
List of tags for the new automation run. If a milestone in the same project has one or more matching automation tags, the new automation run is automatically linked to that milestone (unless milestone or milestone_id is also specified).
 

artifacts array
List of externally stored test artifacts to link to the new automation run (such as log files, screenshots or test data). (see schema for details)
 

fields array
List of fields to attach to the new automation run (such as environment variables, errors or terminal output). (see schema for details)
 

links array
List of links to attach to the new automation run (such as a link back to the build in the CI tool that triggered the tests). (see schema for details)
  

{
  "name": {
      "type": "string",
      "description": "Name of the new automation run (required)."
  },
  "source": {
      "type": "string",
      "description": "Name of the source for the new automation run (required). Created automatically if it does not exist."
  },
  "config": {
      "type": "string",
      "description": "Name of the configuration for the new automation run."
  },
  "config_id": {
      "type": "integer",
      "format": "int64",
      "description": "ID of the configuration. Takes precedence over config if both are specified."
  },
  "milestone": {
      "type": "string",
      "description": "Name of the milestone for the new automation run."
  },
  "milestone_id": {
      "type": "integer",
      "format": "int64",
      "description": "ID of the milestone. Takes precedence over milestone if both are specified."
  },
  "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of tags. Automatically links to a matching milestone if automation tags match."
  },
  "artifacts": {
      "type": "array",
      "description": "List of externally stored test artifacts.",
      "items": {
          "type": "object",
          "required": ["name", "url"],
          "properties": {
              "name": { "type": "string", "description": "Name or file name of the artifact." },
              "url": { "type": "string", "description": "Link to download the artifact." },
              "note": { "type": "string", "description": "Short note (max 80 characters)." },
              "mime_type": { "type": "string", "description": "MIME type (e.g. image/png)." },
              "size": { "type": "integer", "format": "int64", "description": "File size in bytes." }
          }
      }
  },
  "fields": {
      "type": "array",
      "description": "List of fields to attach to the run.",
      "items": {
          "type": "object",
          "required": ["type", "name"],
          "properties": {
              "type": {
                  "type": "integer",
                  "enum": [1, 2, 3, 4, 5],
                  "description": "Field type: 1 = string, 2 = plain text, 3 = HTML, 4 = terminal/console, 5 = URL."
              },
              "name": { "type": "string", "description": "Name of the field." },
              "value": { "type": "string", "description": "Value of the field." },
              "meta": { "type": "object", "description": "Meta fields to attach (key-value pairs)." },
              "is_highlight": { "type": "boolean", "description": "Highlights the field in the UI." }
          }
      }
  },
  "links": {
      "type": "array",
      "description": "List of links to attach to the run.",
      "items": {
          "type": "object",
          "required": ["name", "url"],
          "properties": {
              "name": { "type": "string", "description": "Name of the link." },
              "url": { "type": "string", "description": "URL of the link." },
              "note": { "type": "string", "description": "Short note (max 80 characters)." }
          }
      }
  }
}

Example

POST /api/v1/projects/1/automation/runs
{
    "name": "Backend CI — main branch",
    "source": "backend",
    "tags": ["tag-a", "tag-b"],
    "artifacts": [
        {
            "name": "test-output.log",
            "url": "https://example.com/artifacts/test-output.log",
            "mime_type": "text/plain",
            "size": 102400
        }
    ],
    "fields": [
        {
            "name": "Environment",
            "type": 1,
            "value": "staging"
        }
    ],
    "links": [
        {
            "name": "CI Build #1234",
            "url": "https://ci.example.com/builds/1234"
        }
    ]
}

Returns the ID of the created automation run on success:

 
201 Created
{
    "id": 1
}

Status codes

201 401 403 404422429 (details)

POST /automation/runs/{automation_run_id}/append

Appends test artifacts, fields or links to an existing automation run.

automation_run_id id required
ID of the automation run.
 

Request

Parameters
Schema

artifacts array
List of externally stored test artifacts to link to the automation run. (see schema for details)
 

fields array
List of fields to attach to the automation run. (see schema for details)
 

links array
List of links to attach to the automation run. (see schema for details)
  

{
  "artifacts": {
      "type": "array",
      "description": "List of externally stored test artifacts.",
      "items": {
          "type": "object",
          "required": ["name", "url"],
          "properties": {
              "name": { "type": "string" },
              "url": { "type": "string" },
              "note": { "type": "string", "description": "Max 80 characters." },
              "mime_type": { "type": "string" },
              "size": { "type": "integer", "format": "int64", "description": "File size in bytes." }
          }
      }
  },
  "fields": {
      "type": "array",
      "description": "List of fields to attach.",
      "items": {
          "type": "object",
          "required": ["type", "name"],
          "properties": {
              "type": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=string, 2=text, 3=HTML, 4=terminal, 5=URL." },
              "name": { "type": "string" },
              "value": { "type": "string" },
              "meta": { "type": "object" },
              "is_highlight": { "type": "boolean" }
          }
      }
  },
  "links": {
      "type": "array",
      "description": "List of links to attach.",
      "items": {
          "type": "object",
          "required": ["name", "url"],
          "properties": {
              "name": { "type": "string" },
              "url": { "type": "string" },
              "note": { "type": "string", "description": "Max 80 characters." }
          }
      }
  }
}

Example

POST /api/v1/automation/runs/1/append
{
    "artifacts": [
        {
            "name": "coverage.html",
            "url": "https://example.com/artifacts/coverage.html",
            "mime_type": "text/html",
            "size": 512000
        }
    ],
    "fields": [
        {
            "name": "Build duration",
            "type": 1,
            "value": "4m 32s"
        }
    ],
    "links": [
        {
            "name": "Coverage report",
            "url": "https://example.com/coverage"
        }
    ]
}
 
204 No Content

Status codes

204 401 403 404422429 (details)

POST /automation/runs/{automation_run_id}/complete

Marks an automation run and its threads as completed and closes it for new threads and test results.

automation_run_id id required
ID of the automation run to complete.
 

Request

Parameters
Schema

measure_elapsed boolean
When true, the execution time of the automation run is automatically set to the elapsed time between the creation and completion date. Useful when the overall execution time of the run is independent from the execution times of its threads.
  

{
  "measure_elapsed": {
      "type": "boolean",
      "description": "When true, sets the run's execution time to the elapsed time between creation and completion."
  }
}

Example

POST /api/v1/automation/runs/1/complete
{
    "measure_elapsed": true
}
 
204 No Content

Status codes

204 401 403 404422429 (details)

POST /automation/runs/{automation_run_id}/threads

Creates a new thread in an automation run in preparation for adding test results.

automation_run_id id required
ID of the target automation run.
 

Request

Parameters
Schema

elapsed_observed integer
Observed overall elapsed (execution time) of the thread in microseconds.
 

elapsed_computed integer
Computed overall elapsed (execution time) of the thread in microseconds. The observed elapsed is usually derived from measuring the execution time of tests whereas the computed elapsed is calculated from result log files.
 

artifacts array
List of externally stored test artifacts to link to the new thread. (see schema for details)
 

fields array
List of fields to attach to the new thread. (see schema for details)
  

{
  "elapsed_observed": {
      "type": "integer",
      "format": "int64",
      "description": "Observed overall elapsed (execution time) of the thread in microseconds."
  },
  "elapsed_computed": {
      "type": "integer",
      "format": "int64",
      "description": "Computed overall elapsed of the thread in microseconds."
  },
  "artifacts": {
      "type": "array",
      "description": "List of externally stored test artifacts.",
      "items": {
          "type": "object",
          "required": ["name", "url"],
          "properties": {
              "name": { "type": "string" },
              "url": { "type": "string" },
              "note": { "type": "string" },
              "mime_type": { "type": "string" },
              "size": { "type": "integer", "format": "int64" }
          }
      }
  },
  "fields": {
      "type": "array",
      "description": "List of fields to attach.",
      "items": {
          "type": "object",
          "required": ["type", "name"],
          "properties": {
              "type": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=string, 2=text, 3=HTML, 4=terminal, 5=URL." },
              "name": { "type": "string" },
              "value": { "type": "string" },
              "meta": { "type": "object" },
              "is_highlight": { "type": "boolean" }
          }
      }
  }
}

Example

POST /api/v1/automation/runs/1/threads
{
    "elapsed_observed": 600000000,
    "fields": [
        {
            "name": "Node",
            "type": 1,
            "value": "worker-3"
        }
    ]
}

Returns the ID of the created thread on success:

 
201 Created
{
    "id": 1
}

Status codes

201 401 403 404422429 (details)

POST /automation/runs/threads/{automation_run_thread_id}/append

Appends test artifacts, fields or test results to an existing thread in an automation run.

automation_run_thread_id id required
ID of the automation run thread.
 

Request

Parameters
Schema

elapsed_observed integer
Partial observed elapsed (execution time) in microseconds to add to the overall observed time of the thread.
 

elapsed_computed integer
Partial computed elapsed (execution time) in microseconds to add to the overall computed time of the thread.
 

artifacts array
List of externally stored test artifacts to link to the thread. (see schema for details)
 

fields array
List of fields to attach to the thread. (see schema for details)
 

tests array
List of test results to add to the thread. (see schema for details)
  

{
  "elapsed_observed": {
      "type": "integer",
      "format": "int64",
      "description": "Partial observed elapsed in microseconds to add to the thread total."
  },
  "elapsed_computed": {
      "type": "integer",
      "format": "int64",
      "description": "Partial computed elapsed in microseconds to add to the thread total."
  },
  "artifacts": {
      "type": "array",
      "description": "List of externally stored test artifacts.",
      "items": {
          "type": "object",
          "required": ["name", "url"],
          "properties": {
              "name": { "type": "string" },
              "url": { "type": "string" },
              "note": { "type": "string" },
              "mime_type": { "type": "string" },
              "size": { "type": "integer", "format": "int64" }
          }
      }
  },
  "fields": {
      "type": "array",
      "description": "List of fields to attach.",
      "items": {
          "type": "object",
          "required": ["type", "name"],
          "properties": {
              "type": { "type": "integer", "enum": [1, 2, 3, 4, 5], "description": "1=string, 2=text, 3=HTML, 4=terminal, 5=URL." },
              "name": { "type": "string" },
              "value": { "type": "string" },
              "meta": { "type": "object" },
              "is_highlight": { "type": "boolean" }
          }
      }
  },
  "tests": {
      "type": "array",
      "description": "List of test results to add to the thread.",
      "items": {
          "type": "object",
          "required": ["key", "name", "status", "folder"],
          "properties": {
              "key": {
                  "type": "string",
                  "pattern": "^[a-z0-9_]{1,64}$",
                  "description": "Key used to identify tests across multiple automation runs (max 64 lowercase alphanumeric characters)."
              },
              "name": { "type": "string", "description": "Name of the test." },
              "status": {
                  "type": "string",
                  "pattern": "^[a-z0-9_]+$",
                  "description": "Status alias for the result (e.g. passed, failed). Configured in Testmo's admin area."
              },
              "folder": { "type": "string", "description": "Fully qualified folder name (usually maps to a class or type name)." },
              "elapsed": { "type": "integer", "format": "int64", "description": "Execution time of the test in microseconds." },
              "file": { "type": "string", "description": "File name the test is located in." },
              "line": { "type": "integer", "description": "Line number in the given file." },
              "assertions": { "type": "integer", "description": "Number of assertions in the test." },
              "artifacts": { "type": "array", "description": "Artifacts to link to this test." },
              "fields": { "type": "array", "description": "Fields to attach to this test." }
          }
      }
  }
}

Example

POST /api/v1/automation/runs/threads/1/append
{
    "elapsed_observed": 600000000,
    "tests": [
        {
            "key": "5ccaaa9ca9f351d0c36b45c59728f1a23d16601d",
            "name": "testValidLogin",
            "folder": "com.example.LoginTest",
            "status": "passed",
            "elapsed": 60000000,
            "file": "LoginTest.java",
            "line": 42,
            "assertions": 5
        },
        {
            "key": "7295b69b0df06d518d481c54d71973f9f911520a",
            "name": "testLoginWithInvalidPassword",
            "folder": "com.example.LoginTest",
            "status": "failed",
            "fields": [
                {
                    "name": "Error",
                    "type": 4,
                    "value": "AssertionError: expected 401 but got 200",
                    "meta": { "type": "AssertionError" },
                    "is_highlight": true
                }
            ]
        },
        ..
    ]
}
 
204 No Content

Status codes

204 401 403 404422429 (details)

POST /automation/runs/threads/{automation_run_thread_id}/complete

Marks an automation run thread as completed and closes it for new test results.

automation_run_thread_id id required
ID of the automation run thread to complete.
 

Request

Parameters
Schema

elapsed_observed integer
Observed overall elapsed (execution time) of the thread in microseconds.
 

elapsed_computed integer
Computed overall elapsed (execution time) of the thread in microseconds.
  

{
  "elapsed_observed": {
      "type": "integer",
      "format": "int64",
      "description": "Observed overall elapsed (execution time) of the thread in microseconds."
  },
  "elapsed_computed": {
      "type": "integer",
      "format": "int64",
      "description": "Computed overall elapsed of the thread in microseconds."
  }
}

Example

POST /api/v1/automation/runs/threads/1/complete
{
    "elapsed_observed": 600000000
}
 
204 No Content

Status codes

204 401 403 404422429 (details)

Was this article helpful?