For guidance, examples, and limits, see [Upsert data](/guides/index-data-upsert-data).

:::callout{intent="tip"}
To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data-import-data) instead of upsert.
:::

:::code-group
```shell curl
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl "https://$INDEX_HOST/vectors/upsert" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "vectors": [
      {
        "id": "vec1",
        "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
        "metadata": {"genre": "comedy", "year": 2020}
      },
      {
        "id": "vec2",
        "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2],
        "metadata": {"genre": "documentary", "year": 2019}
      }
    ],
    "namespace": "example-namespace"
  }'
```
:::

`POST /vectors/upsert`

:::code-group
```json title="200"
{
  "upsertedCount": 2
}
```

```json title="400"
{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "<string>"
    }
  ]
}
```

```json title="409"
{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "<string>"
    }
  ]
}
```

```json title="4XX"
{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "<string>"
    }
  ]
}
```

```json title="5XX"
{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "typeUrl": "<string>",
      "value": "<string>"
    }
  ]
}
```
:::

#### Authorizations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Api-Key` | `string` | - |  |

An API Key is required to call Pinecone APIs. Get yours from the [console](https://app.pinecone.io/).

#### Headers

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `X-Pinecone-Api-Version` | `string` | `2026-07` | Required date-based version header |

#### Body

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `vectors` | `object[]` | - | An array containing the vectors to upsert. Recommended batch limit is up to 1000 vectors. |

::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | - | This is the vector's unique id. Required string length: 1 - 512. Example: example-vector-1 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `values?` | `number[]` | - | This is the vector data. On a request it must be non-empty, and at least one value must have a magnitude of 1e-8 or greater — a vector whose values are all smaller than that is rejected as containing only zeros. On a response this is an empty array whenever the record has no dense data to return: on a sparse index, and on any index when values were not requested. The array is therefore not constrained here, because this schema describes both directions. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sparseValues?` | `object` | - | Vector sparse data. Represented as a list of indices and a list of corresponded values, which must be with the same length. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `indices` | `integer[]` | - | The indices of the sparse data. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `values` | `number[]` | - | The corresponding values of the sparse data, which must be with the same length as the indices. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `metadata?` | `object` | - | This is the metadata included in the request. Field names may not begin with $, which is reserved for filter operators. Every other name is accepted, including names that are empty, non-ASCII, or begin with _. |
::::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `namespace?` | `string` | - | The namespace where you upsert records. Example: example-namespace |

#### Response

`200` — A successful response.

The response for the `upsert` operation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `upsertedCount?` | `integer` | - | The number of vectors upserted. Example: 2 |

## Related pages

- [Search with a vector](./database-data-plane-query.md)
- [Search with text](./database-data-plane-search-records.md)
- [Upsert text](./database-data-plane-upsert-records.md)
- [Fetch records](./database-data-plane-fetch.md)
- [Fetch records by metadata](./database-data-plane-fetch-by-metadata.md)
- [Update a record](./database-data-plane-update.md)
- [Delete records](./database-data-plane-delete.md)
- [List record IDs](./database-data-plane-list.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.