> ## Documentation Index > Fetch the complete documentation index at: https://docs.revilico.bio/llms.txt > Use this file to discover all available pages before exploring further. # Start a RevMethyl run > Estimates a person’s biological age from DNA methylation data of one sample, with up to four published epigenetic clocks, compares it with their actual age when given, and flags diseases whose known marker sites look unusual. Takes a table of methylation levels or a raw Illumina IDAT pair; an IDAT run can take about 3 minutes longer. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `clocks`: 4, `maxChronologicalAge`: 130, `samples`: 1. How the engine works and how to read its results: [RevMethyl documentation](/docs/revmethyl). **Scope:** `runs:write`. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/engines/revmethyl/runs openapi: 3.1.0 info: title: Revilico API version: 1.0.0 description: >- Run Revilico's computational chemistry and biology engines from your own code: upload input files, start runs, follow them and read their results. servers: - url: https://public-api.revilico.bio security: - bearerAuth: [] tags: - name: Account description: Who you are, your credits and what your runs have used. - name: Engines description: The engines you can run, their parameter schemas and examples. - name: Files description: 'Upload input files: create an upload, then PUT the bytes.' - name: Runs description: Start, follow and cancel engine runs. - name: Results and outputs description: 'Read what a run produced: results, files and outputs.' - name: Projects description: Group runs into the projects you see in the web app. - name: Sharing description: >- Share runs with people in your organization, as in the web app's Pipeline sharing. - name: Notes description: >- RevNotes: read, write and share the rich-text notes and note folders of the web app's RevNotes panel, in markdown or HTML. - name: Drive description: >- Your RevDrive files and shared drives, as in the web app: browse, read, use files as run inputs, save outputs, and organize. Ids: `dfile_…` and `dfld_…` in a personal Drive, `drive_…` for a shared drive, `sdfile_…` and `sdfld_…` in one. - name: Engine runs description: >- Start a run of one engine, with that engine's parameters and input files. Same endpoint as **Start a run**. - name: Health description: Service status. Needs no API key. paths: /v1/engines/revmethyl/runs: post: tags: - Engine runs summary: Start a RevMethyl run description: >- Estimates a person’s biological age from DNA methylation data of one sample, with up to four published epigenetic clocks, compares it with their actual age when given, and flags diseases whose known marker sites look unusual. Takes a table of methylation levels or a raw Illumina IDAT pair; an IDAT run can take about 3 minutes longer. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `clocks`: 4, `maxChronologicalAge`: 130, `samples`: 1. How the engine works and how to read its results: [RevMethyl documentation](/docs/revmethyl). **Scope:** `runs:write`. operationId: engineRuns.revmethyl requestBody: required: true content: application/json: schema: type: object properties: name: description: A name for the run, shown in the web app. type: string maxLength: 200 parameters: type: object properties: input_type: default: beta_values description: >- What you upload. beta_values: a table of methylation levels per site, in the beta_values input. idat: the two raw scanner files of one Illumina array sample, in red_idat and green_idat. type: string enum: - beta_values - idat clocks: default: - horvath - hannum - phenoage - grimage description: >- Age estimators ("epigenetic clocks") to run. horvath: Horvath 2013, any tissue; hannum: Hannum 2013, blood; phenoage: PhenoAge 2018, blood; grimage: GrimAge 2019, blood. Each uses 36–40 of its published sites. A clock with none of its sites in the data is left out of the results. minItems: 1 maxItems: 4 type: array items: type: string enum: - horvath - hannum - phenoage - grimage chronological_age: description: >- The person’s actual age in years. When given, each clock also reports how far the estimate is above or below it. type: number minimum: 0 maximum: 130 array_type: default: auto description: >- Illumina array the IDAT files come from: 450k, EPIC or EPIC v2, or auto to detect it. Only used with input_type idat. type: string enum: - auto - 450k - epic - epicv2 additionalProperties: false inputs: type: object properties: beta_values: type: string description: >- For input_type beta_values: methylation levels of one sample, one site per row, the Illumina site id (cg…) in the first column and the level from 0 to 1 in the second. Comma- or tab-separated, optionally gzipped; a header row is fine. Further columns are ignored. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: csv, tsv, txt, gz; up to 100 MB. red_idat: type: string description: >- For input_type idat: the red-channel IDAT file (…_Red.idat) of one Illumina 450k, EPIC or EPIC v2 sample. Not gzipped. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: idat; up to 100 MB. green_idat: type: string description: >- For input_type idat: the green-channel IDAT file (…_Grn.idat) of the same sample. Not gzipped. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: idat; up to 100 MB. additionalProperties: false budget: description: Most credits the run may spend; it is stopped beyond that. type: number exclusiveMinimum: 0 projectId: description: >- Add the run to this project (`proj_…`); needs editor or owner on it. type: string additionalProperties: false examples: defaults: summary: >- All four clocks from a table of methylation levels, compared with the donor’s actual age. value: name: Donor 14 blood parameters: chronological_age: 52 inputs: beta_values: file_… idat: summary: >- Start from the raw red and green scanner files of one EPIC array sample. value: name: Donor 14 blood, EPIC parameters: input_type: idat array_type: epic chronological_age: 52 inputs: red_idat: file_… green_idat: file_… two-clocks: summary: Only the Hannum and PhenoAge clocks, without an actual age. value: parameters: clocks: - hannum - phenoage inputs: beta_values: file_… responses: '202': description: OK content: application/json: schema: $ref: '#/components/schemas/Run' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '402': $ref: '#/components/responses/402' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '422': $ref: '#/components/responses/422' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/502' components: schemas: Run: type: object properties: id: type: string description: Run id, `run_…`. engine: type: string description: Engine slug, e.g. `revredox`. name: type: - string - 'null' access: type: string enum: - owner - shared - project description: >- Why you can see the run: you started it, it was shared with you, or it is in a project you belong to. Only the owner can cancel it or read its inputs. owner: type: object properties: name: type: - string - 'null' email: type: string required: - name - email description: Who started the run. status: type: string enum: - queued - running - succeeded - failed - cancelled description: >- queued until the engine picks the run up; succeeded, failed and cancelled are final. statusReason: description: >- Why a cancelled run stopped: `user`, `insufficient_credits` or `budget_exceeded`. Null otherwise. type: - string - 'null' progress: type: number description: Progress the engine reports; 0 until it reports any. createdAt: type: string format: date-time startedAt: anyOf: - type: string format: date-time - type: 'null' endedAt: anyOf: - type: string format: date-time - type: 'null' budget: description: Most credits the run may spend, if one was set. type: - number - 'null' creditsUsed: type: number description: Credits charged to the run so far. error: anyOf: - type: object properties: message: type: string required: - message - type: 'null' description: Set when status is failed. children: type: object properties: total: type: number queued: type: number running: type: number succeeded: type: number failed: type: number cancelled: type: number required: - total - queued - running - succeeded - failed - cancelled description: >- For engines that run each input as its own job: how many children are in each status. GET /v1/runs/{runId}/children lists them. links: type: object propertyNames: type: string additionalProperties: type: string description: >- Related endpoints: self, inputs (owner only), results, outputs, files. warnings: description: >- Set when the run was created but a follow-up step, such as adding it to a project, failed. type: array items: type: string required: - id - engine - name - access - owner - status - statusReason - progress - createdAt - startedAt - endedAt - budget - creditsUsed - error - links Error: type: object properties: error: type: object properties: code: type: string enum: - VALIDATION_FAILED - INVALID_ID - INVALID_PARAMETERS - INPUT_LIMIT_EXCEEDED - NOT_FOUND - FORBIDDEN - METHOD_NOT_ALLOWED - CONFLICT - PAYLOAD_TOO_LARGE - MISSING_CREDENTIALS - INVALID_CREDENTIALS - WRONG_ENVIRONMENT - CREDENTIALS_EXPIRED - CREDENTIALS_REVOKED - ACCOUNT_INACTIVE - API_ACCESS_NOT_ENABLED - INSUFFICIENT_SCOPE - SESSION_REQUIRED - TOO_MANY_AUTH_FAILURES - API_KEY_LIMIT_REACHED - ENGINE_NOT_ENABLED - DOCS_NOT_AVAILABLE - INSUFFICIENT_CREDITS - RUN_NOT_COMPLETE - ENGINE_SUBMIT_FAILED - RATE_LIMITED - SERVICE_UNAVAILABLE - INTERNAL_ERROR description: Stable within /v1; branch on this, not on the message. message: type: string description: Readable explanation, for people. details: description: >- Extra context, e.g. `issues` ({ path, message }[]) for validation errors. type: object propertyNames: type: string additionalProperties: {} required: - code - message required: - error responses: '400': description: >- The request is malformed. `error.code` is one of `VALIDATION_FAILED`, `INVALID_ID`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_FAILED message: The request is malformed. '401': description: >- The API key is missing or not valid. `error.code` is one of `MISSING_CREDENTIALS`, `INVALID_CREDENTIALS`, `WRONG_ENVIRONMENT`, `CREDENTIALS_EXPIRED`, `CREDENTIALS_REVOKED`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: MISSING_CREDENTIALS message: The API key is missing or not valid. '402': description: >- Your organization doesn't have enough credits. `error.code` is one of `INSUFFICIENT_CREDITS`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INSUFFICIENT_CREDITS message: Your organization doesn't have enough credits. '403': description: >- The key may not do this. `error.code` is one of `INSUFFICIENT_SCOPE`, `API_ACCESS_NOT_ENABLED`, `ENGINE_NOT_ENABLED`, `ACCOUNT_INACTIVE`, `FORBIDDEN`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INSUFFICIENT_SCOPE message: The key may not do this. '404': description: Not found, or not visible to you. `error.code` is one of `NOT_FOUND`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Not found, or not visible to you. '422': description: >- The parameters or input files don't fit the engine. `error.code` is one of `INVALID_PARAMETERS`, `INPUT_LIMIT_EXCEEDED`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_PARAMETERS message: The parameters or input files don't fit the engine. '500': description: >- Something went wrong on our side. `error.code` is one of `INTERNAL_ERROR`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: Something went wrong on our side. '502': description: >- The engine service rejected or failed the request. `error.code` is one of `ENGINE_SUBMIT_FAILED`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ENGINE_SUBMIT_FAILED message: The engine service rejected or failed the request. securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key from the web app (**Settings → Developer**), sent as `Authorization: Bearer rvl_live_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.