Pinecone Getting Started Guide: Quick Setup and First API Call (2026)

Getting started overview

This guide provides a focused walkthrough for developers to begin using Pinecone, covering account creation, API key retrieval, and the execution of a first request. Pinecone is a vector database designed for managing and searching high-dimensional vectors, enabling applications like semantic search and recommendation systems Pinecone platform overview. The process includes signing up for a free tier account, obtaining necessary API credentials, and initializing a connection to an index. Developers can interact with Pinecone through its official SDKs, with Python and Node.js being commonly used for initial setup and operations Pinecone documentation.

The following table outlines the key steps to get started with Pinecone:

Create an account and get keys

Before making any API calls, a Pinecone account is required. Pinecone offers a free tier that supports a single project and index with capacity for up to 500,000 vectors and 1 GB of storage Pinecone pricing details. This tier is suitable for initial development and testing.

1. Sign Up for a Pinecone Account: Navigate to the Pinecone pricing page and select the option to start with the free tier. Complete the registration process, which typically involves providing an email address and creating a password.
2. Access the Pinecone Console: After registration, log in to the Pinecone Console. This web interface allows for managing projects, indexes, and API keys.
3. Create a Project (if prompted): If it's your first time, you might be prompted to create a new project. Projects help organize your indexes and resources.
4. Locate API Keys: In the Pinecone console, navigate to the API Keys section. Here, you will find your default API key and the associated environment. The environment specifies the region where your indexes are hosted (e.g., us-west-2, gcp-starter). Both the API key and the environment string are necessary for authenticating API requests from your application Pinecone API key management. Store these credentials securely.

For programmatic access, these credentials will be passed to the Pinecone client library.

Your first request

This section demonstrates how to make a first request using the Python SDK, as it is widely used and well-documented Pinecone documentation for developers.

1. Install the Pinecone Python SDK

Open your terminal or command prompt and run the following command to install the Pinecone client library:

pip install pinecone-client

2. Initialize the Pinecone Client

In your Python script, import the Pinecone class and initialize it with your API key and environment. Replace "YOUR_API_KEY" and "YOUR_ENVIRONMENT" with the credentials obtained from the Pinecone console.

from pinecone import Pinecone, Index

# Initialize Pinecone
api_key = "YOUR_API_KEY"
environment = "YOUR_ENVIRONMENT" # e.g., "gcp-starter"

pinecone = Pinecone(api_key=api_key, environment=environment)

print("Pinecone client initialized successfully.")

3. Create an Index

An index is where your vectors are stored. For the free tier, you can create one index. When creating an index, you need to specify its name, dimension (the length of your vectors), and metric type (e.g., "cosine", "euclidean", "dotproduct"). This example creates an index with 1536 dimensions, suitable for embeddings from models like OpenAI's text-embedding-ada-002 Google's definition of embeddings.

index_name = "my-first-index"

# Check if index already exists
if index_name not in pinecone.list_indexes():
    pinecone.create_index(
        name=index_name,
        dimension=1536,  # Example dimension, e.g., for OpenAI embeddings
        metric="cosine",
        spec={"serverless": {"cloud": "aws", "region": "us-west-2"}}
    )
    print(f"Index '{index_name}' created.")
else:
    print(f"Index '{index_name}' already exists.")

# Connect to the index
index = pinecone.Index(index_name)
print(f"Connected to index '{index_name}'.")

Note: The spec parameter is crucial for Serverless indexes, specifying the cloud provider and region. For free tier accounts, "gcp-starter" is often the default environment, and Pinecone automatically manages the underlying infrastructure Pinecone Serverless index management.

4. Insert Data (Upsert Vectors)

To populate the index, you'll "upsert" vectors. This operation inserts new vectors or updates existing ones. Each vector requires a unique ID, the vector values (a list of floats), and optionally, metadata.

import random

# Example vectors (replace with your actual embedding data)
data_to_upsert = [
    {"id": "vec1", "values": [random.random() for _ in range(1536)], "metadata": {"genre": "fiction", "year": 2023}},
    {"id": "vec2", "values": [random.random() for _ in range(1536)], "metadata": {"genre": "non-fiction", "year": 2022}},
    {"id": "vec3", "values": [random.random() for _ in range(1536)], "metadata": {"genre": "science", "year": 2024}}
]

# Upsert vectors to the index
index.upsert(vectors=data_to_upsert)
print(f"Successfully upserted {len(data_to_upsert)} vectors to '{index_name}'.")

# Check index statistics (optional)
print("Index statistics:", index.describe_index_stats())

5. Query the Index

Once data is in the index, you can query it using a query vector. Pinecone will return the most similar vectors based on the configured metric.

# Example query vector (replace with an actual embedding from your application)
query_vector = [random.random() for _ in range(1536)]

# Perform a query
query_results = index.query(
    vector=query_vector,
    top_k=2, # Number of nearest neighbors to retrieve
    include_values=False, # Whether to include the vector values in the response
    include_metadata=True # Whether to include metadata in the response
)

print("Query Results:")
for match in query_results.matches:
    print(f"  ID: {match.id}, Score: {match.score}, Metadata: {match.metadata}")

Common next steps

After successfully completing your first request, several common next steps can enhance your Pinecone integration:

• Integrate with Embedding Models: Connect Pinecone with an embedding model (e.g., from OpenAI, Hugging Face, or Cohere) to convert text, images, or other data into vectors. This is a fundamental step for building semantic search or RAG applications Pinecone OpenAI integration guide.
• Advanced Index Management: Explore features like namespaces for partitioning data, updating vectors, or deleting vectors and indexes Pinecone index management documentation.
• Metadata Filtering: Utilize metadata to filter search results, allowing for more precise and context-aware queries. This is powerful for refining search based on attributes like category, date, or author.
• Error Handling and Retries: Implement robust error handling and retry mechanisms in your application to manage transient network issues or rate limits, as recommended for any API integration AWS guidance on error retries.
• Monitor Performance: Use the Pinecone console to monitor index performance, vector count, and query latency to optimize your application.
• Explore Other SDKs: If Python is not your primary development language, consider exploring the Node.js, Go, or Java SDKs for Pinecone.
• Security Best Practices: Ensure your API keys are managed securely, for instance, by using environment variables or a secrets manager, rather than hardcoding them directly into your application code.

Troubleshooting the first call

Encountering issues during the initial setup is common. Here are some troubleshooting tips for your first Pinecone API call:

• Invalid API Key or Environment: Double-check that the api_key and environment strings in your code exactly match those provided in your Pinecone console. Typos or incorrect values are a frequent source of authentication errors.
• Index Not Found: If you receive an error indicating the index does not exist, verify the index_name in your code. Ensure it matches the name you used when creating the index. Also, confirm the index has finished provisioning in the Pinecone console, which can take a few minutes.
• Dimension Mismatch: The dimension of vectors you upsert or query must precisely match the dimension specified when the index was created. A mismatch will result in an error during upsert or query operations.
• Rate Limiting: While less common for a first call on the free tier, excessive requests can lead to rate limiting errors. Pinecone's API has usage limits Pinecone service limits. If you suspect this, introduce delays between calls or implement a backoff strategy.
• Network Connectivity: Ensure your development environment has stable internet access and is not blocked by a firewall from reaching Pinecone's endpoints.
• Incorrect SDK Version: Ensure you have the latest version of the Pinecone SDK installed. Outdated versions might have bugs or lack support for newer features. You can update using pip install --upgrade pinecone-client.
• Check Pinecone Status Page: Occasionally, service outages can occur. Check the official Pinecone Status Page for any reported incidents that might affect service availability.
• Review Documentation and Examples: Consult the Pinecone official documentation and code examples for specific guidance related to your use case or programming language.