---
title: Wellbore Plunger
slug: wellbore-plunger
docTags: 
createdAt: 2026-07-06T20:57:51.248Z
---

The Wellbore Plunger table describes plungers installed in the well, used for plunger lift modeling. A plunger belongs to a tubing string — **sourceTubingId** must match an existing [Wellbore Tubing](docId\:T6SGY9Y9XNVaBpQNNqotq) record.

The unique constraint on plunger entries is **sourceTubingId + sourceId**.

:::hint{type="warning"}
The tubing string referenced by **sourceTubingId** must be loaded before adding a plunger to it.
:::

| **Variable**      | **Data Type**   | **Unit of Measure** | **Is Nullable?** | **Default Value** | **Description**                                                                                                                                        |
| ----------------- | --------------- | ------------------- | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| sourceId          | String          | -                   | No               | -                 | Unique identifier of the plunger, to enable upserts                                                                                                    |
| sourceWellId      | String          | -                   | No               | -                 | Source ID for the well. Must match the sourceId of a record in the [Well](docId\:P-xHbe4jqKJQemay7aOL5) table.                                         |
| sourceWellboreId  | String          | -                   | No               | -                 | Source ID for the wellbore. Must match the sourceId of a record in the [Wellbore](docId\:XPqwCAS8aWDaWyssmVjY6) table.                                 |
| sourceTubingId    | String          | -                   | No               | -                 | Source ID of the tubing string in which the plunger is installed. Must match the sourceId of a [Wellbore Tubing](docId\:T6SGY9Y9XNVaBpQNNqotq) record. |
| runDate           | Datetime Offset | -                   | No               | -                 | Date the plunger was installed. Datetime offset (with timezone) in ISO 8601 format. Example: 2022-09-27T16:28:37+0000                                  |
| pullDate          | Datetime Offset | -                   | Yes              | -                 | Date the plunger was removed from the well. Datetime offset (with timezone) in ISO 8601 format.                                                        |
| make              | String          | -                   | No               | -                 | Manufacturer of the plunger installed                                                                                                                  |
| model             | String          | -                   | No               | -                 | Manufacturer-assigned model of the plunger                                                                                                             |
| type              | String          | -                   | No               | -                 | Source-provided plunger classification in the well (e.g., conventional, bypass, pad, free cycle, etc.)                                                 |
| bumperSpringDepth | Double          | ft                  | No               | -                 | Measured depth of the bumper spring installation — the landing depth where the plunger comes to rest at the bottom of the well                         |

***

# Data Integrity Checks

| **Condition**                                                                      | **Response**    |
| ---------------------------------------------------------------------------------- | --------------- |
| Any non-nullable field is NULL or empty                                            | Record Rejected |
| (sourceWellId, sourceWellboreId, sourceTubingId) does not match an existing tubing | Row Skipped     |

:::hint{type="info"}
**Partial success on bulk ingest**

Rows referencing an unknown tubing string are skipped while the remaining rows are written. The error response names each skipped row. An error response therefore does not mean nothing was written.
:::

***

# Common Error Messages

| **API**              | **Scenario**   | **Error Response**                                                                                                                                |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Add / Upsert plunger | Unknown tubing | WellborePlunger with sourceId 'xxx' was skipped: tubing with sourceWellId 'xxx' and sourceWellboreId 'xxx' and sourceTubingId 'xxx' was not found |