> ## 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 Rev SingleCell run > Analyses single-cell RNA-seq data: filters out poor-quality cells, groups similar cells into clusters, labels each cluster with a likely cell type and lists its marker genes. Optionally corrects batch effects, scores transcription factor and pathway activity, compares control with experimental cells, looks up the genes that change most, and orders cells by pseudotime. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `markerGenesPerCluster`: 50, `differentialGenesPerGroup`: 50, `genesLookedUp`: 50. How the engine works and how to read its results: [Rev SingleCell documentation](/docs/revsinglecell). **Scope:** `runs:write`. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/engines/revsinglecell/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/revsinglecell/runs: post: tags: - Engine runs summary: Start a Rev SingleCell run description: >- Analyses single-cell RNA-seq data: filters out poor-quality cells, groups similar cells into clusters, labels each cluster with a likely cell type and lists its marker genes. Optionally corrects batch effects, scores transcription factor and pathway activity, compares control with experimental cells, looks up the genes that change most, and orders cells by pseudotime. Starts a run and returns it with status `queued`; poll GET /v1/runs/{runId} until it finishes. Runs spend credits. **Limits:** `markerGenesPerCluster`: 50, `differentialGenesPerGroup`: 50, `genesLookedUp`: 50. How the engine works and how to read its results: [Rev SingleCell documentation](/docs/revsinglecell). **Scope:** `runs:write`. operationId: engineRuns.revsinglecell 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: min_genes: default: 200 description: >- Drop cells with fewer detected genes than this (empty droplets, broken cells). type: integer minimum: 50 maximum: 5000 max_genes: default: 6000 description: >- Drop cells with more detected genes than this (likely two cells captured together). Must be above min_genes. type: integer minimum: 500 maximum: 20000 max_pct_mt: default: 20 description: >- Drop cells where this percentage or more of the reads come from mitochondrial genes (MT-…), a sign of dying cells. type: number exclusiveMinimum: 0 maximum: 100 resolution: default: 0.5 description: >- Clustering resolution: higher splits the cells into more, smaller clusters. type: number minimum: 0.1 maximum: 2 batch_key: description: >- Turns on batch correction (Harmony): the name of the cell metadata column that says which batch (sample, donor, run) each cell came from. Only h5ad files carry such columns. Skipped, without failing the run, when the column is missing or holds a single value; the results' batchCorrected says whether it ran. type: string pattern: ^[A-Za-z0-9_.-]{1,64}$ tf_activity: default: false description: >- Score how active each transcription factor (a gene that switches other genes on or off) is in every cell, from its known target genes (DoRothEA, human). type: boolean pathway_activity: default: false description: >- Score 14 signalling pathways (PROGENy, human: EGFR, MAPK, TNFa, p53…) in every cell. type: boolean differential_expression: default: false description: >- Find the genes that differ most between groups: control vs experimental when an experimental file is given, otherwise each cluster vs the other cells. type: boolean target_identification: default: false description: >- Look up the top differentially expressed genes (up to 50) for name, function summary, pathways and druggability class. Needs differential_expression. type: boolean pseudotime: default: false description: >- Order the cells along a developmental path (pseudotime; RNA velocity when an h5ad file has spliced and unspliced count layers) and find the genes that change along it in each cluster. type: boolean additionalProperties: false inputs: type: object properties: control: type: string description: >- The dataset to analyse: gene counts per cell. AnnData (h5ad), 10x Genomics HDF5 (h5), or a matrix with cell names in the first column and gene symbols in the header: CSV (comma), TSV or TXT (tab); genes as rows is detected and flipped. Raw counts, not gzipped. Mitochondrial genes must be named MT-… for the max_pct_mt filter. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: h5ad, h5, csv, tsv, txt; up to 100 MB. experimental: type: string description: >- Optional second dataset in the same form (e.g. treated cells), only used with differential_expression: its cells are pooled with the control cells, keeping the genes both files share, and the two groups are compared. A file id: an upload (`file_…`) or a Drive file (`dfile_…`, `sdfile_…`). Formats: h5ad, h5, csv, tsv, txt; up to 100 MB. required: - control 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 required: - inputs additionalProperties: false examples: defaults: summary: >- Filter, cluster and label the cell types of one single-cell dataset. value: name: PBMC 10k clusters parameters: {} inputs: control: file_… control-vs-treated: summary: >- Compare treated cells with untreated ones and look up the genes that change most. value: name: PBMC baseline vs stimulated parameters: differential_expression: true target_identification: true inputs: control: file_… experimental: file_… batches-and-activity: summary: >- Correct for donor batches in an h5ad file, then score transcription factor and pathway activity and order the cells by pseudotime. value: parameters: resolution: 0.8 batch_key: donor tf_activity: true pathway_activity: true pseudotime: true inputs: control: 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.