> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.benchling.com/in-vivo/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/in-vivo/_mcp/server. # Retrieve a study animal dosage GET https://acme-api.invivo.benchling.com/api/public/v1/studies/{studyId}/animals/{animalId}/dosages/{dosageId} Retrieves a single dose administered to an animal on a study. Reference: https://docs.benchling.com/in-vivo/study-animal-dosages/study-animal-dosage-get ## Authentication - OAuth2 — send the obtained token as `Authorization: Bearer ` ## Request ### Path parameters - `studyId` (string, required) — The unique identifier of the study. - `animalId` (string, required) — The unique identifier of the animal. - `dosageId` (string, required) — The unique identifier of the dosage. ## Response ### 200 The requested dosage. - `id` (string, required) — Unique identifier for a dosage. - `name` (string, required, nullable) — The name of the dosage. - `dosed_at` (datetime, required, nullable) — The time the dose was administered, which may be earlier than `created_at` when it was recorded retrospectively. - `comments` (string, required, nullable) — Any note recorded alongside the dosage. - `weight_at_dosing` (string, required, nullable) — The animal's weight used to scale the dose, as a string so that the precision recorded is preserved exactly. Null when the dose was not scaled to weight. - `dose` (DoseV1, required, nullable) — The dose administered, relative to body weight. - `dose_volume` (DoseVolumeV1, required, nullable) — The volume administered, relative to body weight. - `stock` (StockV1, required, nullable) — The concentration of the stock solution the dose was drawn from. - `volume` (VolumeV1, required, nullable) — The absolute volume administered. - `study` (StudyNestedV1, required, nullable) — The study the dosage was given under, taken from its treatment. - `animal` (AnimalNestedV1, required) — The animal a record belongs to, as embedded in dosages, measurements, observations and samples. Carries the same attributes as an animal retrieved directly, except that the cage, study and treatment group are given as identifiers rather than embedded objects. - `measurement` (MeasurementNestedV2, required, nullable) — The measurement the dose was scaled from. Null when the dose was not scaled to a recorded weight. - `user` (UserV1, required, nullable) — The user who administered the dose. - `treatment` (TreatmentNestedV1, required) — The treatment a dosage was given under, as embedded in dosages. A treatment belongs to a study and defines what is administered and how much; the quantities here are the treatment's prescribed amounts, which may differ from the amounts actually recorded on an individual dosage. - `created_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. - `updated_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. ## Errors ### 400 Bad Request Error The request was rejected. Validation failures return a `ValidationErrorResponse`; an unrecognised `X-Studies-Api-Version` header returns an `AuthErrorResponse` with the code `invalid_header`. - `BadRequestErrorResponse` ### 401 Unauthorized Error Authentication failed. The body is normally empty; when an otherwise valid access token is missing required claims the body is an `AuthErrorResponse` with the code `invalid_token`. - `any` ### 403 Forbidden Error The access token does not grant the scopes this operation requires. The body is normally empty; when the token's team is missing or deleted the body is an `AuthErrorResponse` with the code `invalid_data`. - `any` ### 404 Not Found Error No resource matching the given identifier exists on your team. The body is empty. - `any` ### 429 Too Many Requests Error A rate limit was exceeded. Retry once the window resets; no `Retry-After` header is sent, so use `X-RateLimit-Reset`. - `error` ("rate_limit_exceeded", required) — A machine-readable error code. - `message` (string, required) — A human-readable explanation of the failure. ## Types ### DoseV1 The amount of the compound administered, relative to the animal's body weight. Quantities are strings rather than numbers so that the precision recorded is preserved exactly. The `display_` pair carries the same quantity converted into the unit your team has chosen to work in, which may differ from the unit it was recorded in. - `unit` (string, required, nullable) — The unit the dose was recorded in. - `value` (string, required, nullable) — The dose, in `unit`. - `display_unit` (string, required, nullable) — The unit the dose is displayed in. - `display_value` (string, required, nullable) — The dose, in `display_unit`. ### DoseVolumeV1 The volume administered, relative to the animal's body weight. Quantities are strings rather than numbers so that the precision recorded is preserved exactly. The `display_` pair carries the same quantity converted into the unit your team has chosen to work in, which may differ from the unit it was recorded in. - `unit` (string, required, nullable) — The unit the dose volume was recorded in. - `value` (string, required, nullable) — The dose volume, in `unit`. - `display_unit` (string, required, nullable) — The unit the dose volume is displayed in. - `display_value` (string, required, nullable) — The dose volume, in `display_unit`. ### StockV1 The concentration of the stock solution the dose was drawn from. Quantities are strings rather than numbers so that the precision recorded is preserved exactly. The `display_` pair carries the same quantity converted into the unit your team has chosen to work in, which may differ from the unit it was recorded in. - `unit` (string, required, nullable) — The unit the stock concentration was recorded in. - `value` (string, required, nullable) — The stock concentration, in `unit`. - `display_unit` (string, required, nullable) — The unit the stock concentration is displayed in. - `display_value` (string, required, nullable) — The stock concentration, in `display_unit`. ### VolumeV1 The absolute volume administered. Quantities are strings rather than numbers so that the precision recorded is preserved exactly. The `display_` pair carries the same quantity converted into the unit your team has chosen to work in, which may differ from the unit it was recorded in. - `unit` (string, required, nullable) — The unit the volume was recorded in. - `value` (string, required, nullable) — The volume, in `unit`. - `display_unit` (string, required, nullable) — The unit the volume is displayed in. - `display_value` (string, required, nullable) — The volume, in `display_unit`. ### StudyNestedV1 The study a record belongs to, as embedded in animals, dosages, measurements, observations and samples. Carries the same attributes as a study retrieved directly, except that the project is given as an identifier rather than an embedded object. - `id` (string, required) — Unique identifier for a study. - `project_id` (string, required, nullable) — The project of the study. Null when the study is not in a project. - `name` (string, required) — The name of the study. - `code` (string, required, nullable) — The code of the study. - `study_code_id` (string, required, nullable) — The unique identifier of the study code template. - `type` (enum, required) — Whether the study is run in-house or by an external partner. The `all` value accepted by some filters is not a valid study type and is never returned. - Allowed values: `internal`, `external` - `status` (enum, required) — Review status of a study. - Allowed values: `awaiting_approval`, `in_progress`, `rejected` - `description` (string, required, nullable) — The description of the study. - `timezone` (string, required, nullable) — The timezone of the study, as an IANA timezone identifier. - `metadata` (map from string to any, required, nullable) — The metadata associated to the study. - `author` (StudyAuthorUserV1, required, nullable) — The author of the study. - `owner` (StudyAuthorUserV1, required, nullable) — The owner of the study. - `started_on` (date, required) — Calendar date with no time or offset component, in ISO-8601 form. - `tracking_day_base` (integer, required, nullable) — The day number assigned to the study's start date, from which all subsequent tracking days are counted. - `completed_at` (datetime, required, nullable) — The completed timestamp of the study. - `canceled_at` (datetime, required, nullable) — The canceled timestamp of the study. - `created_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. - `updated_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. ### AnimalNestedV1 The animal a record belongs to, as embedded in dosages, measurements, observations and samples. Carries the same attributes as an animal retrieved directly, except that the cage, study and treatment group are given as identifiers rather than embedded objects. - `id` (string, required) — Unique identifier for an animal. - `name` (string, required) — The name of the animal. - `number` (integer, required) — The position of the animal within its cage. - `catalog` (string, required, nullable) — The catalog number of the animal. - `species` (string, required, nullable) — The species of the animal, derived from its strain. Null when the animal has no strain assigned. - `strain` (string, required, nullable) — The strain of the animal. - `sex` (enum, required, nullable) — The sex of the animal. - Allowed values: `m`, `f`, `u` - `dob` (date, required, nullable) — The date of birth of the animal. - `donor` (string, required, nullable) — The donor identifier of the animal. - `ear` (string, required, nullable) — The ear marking identifying the animal. - `tag` (string, required, nullable) — The tag identifying the animal. - `tail` (string, required, nullable) — The tail marking identifying the animal. - `cage_id` (string, required, nullable) — The cage the animal is housed in. - `study_id` (string, required, nullable) — The study the animal is enrolled on. Null when it is not on a study. - `study_group_id` (string, required, nullable) — The treatment group the animal is assigned to. Null when it is not on a study, or is on one but not yet grouped. - `tracking_date` (date, required, nullable) — The date from which the animal's tracking days are counted. - `disease_induction_date` (date, required, nullable) — The date the animal had a disease induced. - `disease_survivor` (boolean, required, nullable) — Whether the animal survived the induced disease. - `terminated_at` (date, required, nullable) — The date the animal was terminated. Null while the animal is alive. - `terminated_by` (StudyAuthorUserV1, required, nullable) — The user who recorded the termination. - `terminated_reason` (AnimalTerminatedReasonV1, required, nullable) — Why the animal was terminated. - `metadata` (map from string to any, required, nullable) — The metadata associated to the animal. - `created_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. - `updated_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. ### MeasurementNestedV2 The measurement a dosage was calculated from, as embedded in dosages. Carries the same attributes as a measurement retrieved directly, except that the animal and study are given as identifiers rather than embedded objects, and the recording user is omitted. Only calculations that still have a stored value are included. - `id` (string, required) — Unique identifier for a measurement. - `study_id` (string, required, nullable) — The study the animal was on when the readings were taken. Null when the animal is not on a study. - `animal_id` (string, required) — Unique identifier for an animal. - `measured_at` (date, required, nullable) — The date the readings were taken, which may be earlier than `created_at` when they were recorded retrospectively. - `calculations` (list of CalculationV2, required) — The values recorded and derived, one entry per configured calculation. - `created_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. - `updated_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. ### UserV1 A member of your team, as referenced by the records they created. This is the fuller user representation; studies reference a narrower one that omits `status`, `metadata` and the timestamps. - `id` (string, required) — Unique identifier for a user. - `name` (string, required) — The name of the user. - `email` (string, required) — The email address of the user. - `timezone` (string, required, nullable) — The timezone of the user, as an IANA timezone identifier. - `status` (enum, required) — The standing of a user within your team. `pending` means the invitation has not yet been accepted, and `revoked` means access was withdrawn. - Allowed values: `active`, `pending`, `inactive`, `revoked` - `metadata` (map from string to any, required, nullable) — The metadata associated to the user. - `created_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. - `updated_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. ### TreatmentNestedV1 The treatment a dosage was given under, as embedded in dosages. A treatment belongs to a study and defines what is administered and how much; the quantities here are the treatment's prescribed amounts, which may differ from the amounts actually recorded on an individual dosage. - `id` (string, required) — Unique identifier for a treatment. - `study_id` (string, required) — Unique identifier for a study. - `type` (enum, required, nullable) — How the amount to administer is derived. - Allowed values: `concentration`, `concentration_mlkg`, `concentration_vgkg`, `custom`, `dose_volume`, `volume` - `name` (string, required, nullable) — The name of the compound or article administered. - `label` (string, required) — The label identifying the treatment within its study. - `dose` (DoseV1, required, nullable) — The prescribed dose, relative to body weight. - `dose_volume` (DoseVolumeV1, required, nullable) — The prescribed volume, relative to body weight. - `stock` (StockV1, required, nullable) — The concentration of the stock solution the dose is drawn from. - `volume` (VolumeV1, required, nullable) — The prescribed absolute volume. - `metadata` (map from string to any, required, nullable) — The metadata associated to the treatment. - `external_entity_id` (string, required, nullable) — The identifier of the Benchling entity the treatment is linked to. Null when the treatment is not linked to one. - `created_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. - `updated_at` (datetime, required) — UTC timestamp with microsecond precision, always suffixed with `Z`, in the form `yyyy-MM-ddTHH:mm:ss.SSSSSSZ`. ### ValidationErrorResponse Returned when a request body or parameter fails validation. - `message` (string, required) — A summary of the failure. - `errors` (map from string to list of string, required) — Failure messages keyed by the offending field, using the field's name as it appears on the wire. Nested fields are dotted, e.g. `schedule.duration`. ### AuthErrorResponse Returned when a request is rejected during authentication, before it is processed. - `error` (enum, required) — A machine-readable error code. - Allowed values: `invalid_header`, `invalid_token`, `invalid_data` - `error_description` (string, required) — A human-readable explanation of the failure. ### ProblemDetail An RFC 9457 problem detail, returned when a request is rejected before it reaches a controller method — most commonly an unparseable or absent JSON body. Unlike the rest of this API, null members are omitted rather than serialised as `null`. - `title` (string, required) — A short, human-readable summary of the problem type. - `status` (integer, required) — The HTTP status code, repeated in the body. - `detail` (string, required) — A human-readable explanation specific to this occurrence. - `instance` (string, required) — The path of the request that produced the problem. ### StudyAuthorUserV1 A user referenced as the author or owner of a study. - `id` (string, required) — Unique identifier for a user. - `name` (string, required) — The name of the user. - `email` (string, required) — The email address of the user. - `timezone` (string, required) — The timezone of the user. Defaults to `UTC` when the user has none set. ### AnimalTerminatedReasonV1 Why an animal was terminated. The reason is chosen from the shared glossary, or recorded free-form when no glossary entry fits. - `glossary_id` (string, required, nullable) — The glossary entry the reason was chosen from. Null when the reason was recorded free-form. - `title` (string, required, nullable) — The reason for the termination. - `comment` (string, required, nullable) — Any further detail recorded alongside the reason. ### CalculationV2 One value on a measurement, together with the readings it was derived from. A calculation is either a reading taken directly — in which case `formula` is just its own key and `variables` holds the single reading — or a value computed from several readings, in which case `variables` holds one entry per term in `formula`. Which calculations a measurement carries is determined by your team's measurement settings, not by the API. - `id` (string, required, nullable) — The recorded value this calculation came from. Null for a derived calculation that has no stored value of its own. - `key` (string, required, nullable) — The slug identifying the calculation in your team's measurement settings. - `name` (string, required, nullable) — The display name of the calculation. - `unit` (string, required, nullable) — The unit the calculation is expressed in. - `excluded` (boolean, required) — Whether the value has been excluded from analysis. An excluded value is still returned; it is left out of aggregates and charts. - `value` (string, required, nullable) — The calculated value, as a string so that the precision recorded is preserved exactly. - `formula` (string, required, nullable) — The expression the value was computed from, written in terms of the `key` of each variable. A directly recorded reading has its own key as the formula. - `variables` (list of VariableV2, required) — The readings the value was computed from. ### VariableV2 One input to a calculation. A calculation that is a single recorded reading has one variable holding that reading; a derived calculation has one variable per reading its formula combines. - `id` (string, required, nullable) — The reading the value was recorded against. Null when the reading is no longer configured for your team. - `key` (string, required, nullable) — The slug identifying the reading in your team's measurement settings. - `value` (string, required, nullable) — The recorded value, as a string so that the precision recorded is preserved exactly. - `unit` (string, required, nullable) — The unit the value was recorded in. ## Examples **Response** ```json { "error": "string", "message": "Too many requests" } ``` **SDK Code** ```python import requests url = "https://acme-api.invivo.benchling.com/api/public/v1/studies/sdy_3vQ8kZpLmN2xRt7YwBcDfG/animals/aml_7KpQ2mNvR4tXwZ9bYcDfGh/dosages/dsg_2kQ7mNvR8tXwZ4bYcPfGh5" headers = {"Authorization": "."} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://acme-api.invivo.benchling.com/api/public/v1/studies/sdy_3vQ8kZpLmN2xRt7YwBcDfG/animals/aml_7KpQ2mNvR4tXwZ9bYcDfGh/dosages/dsg_2kQ7mNvR8tXwZ4bYcPfGh5'; const options = {method: 'GET', headers: {Authorization: '.'}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ```