Pinecone Getting Started: Account, Keys, First Request (2026)

Getting started overview

This guide provides the necessary steps to get started with Pinecone, a specialized vector database designed for real-time AI applications such as semantic search and recommendation systems. The process involves creating an account, obtaining API credentials, and executing a foundational API request. Pinecone offers client libraries for Python, Node.js, Go, and Java, alongside a direct REST API interface.

Before making your first API call, you will need to:

1. Sign up for a Pinecone account.
2. Generate or locate your API key and environment.
3. Install the relevant Pinecone client library for your preferred programming language.
4. Initialize a Pinecone index.
5. Perform a basic operation, such as upserting a vector.

The following table summarizes the key steps:

Create an account and get keys

To begin, navigate to the Pinecone website and sign up for an account. Pinecone offers a Starter free tier that supports up to 50,000 vectors and one index, which is suitable for initial development and testing.

Account Registration

1. Go to the Pinecone homepage.
2. Click on the "Sign Up" or "Get Started Free" button.
3. Follow the prompts to create your account, which may involve email verification.

API Key and Environment Retrieval

After successfully registering and logging into your Pinecone console, you will find your API credentials. These credentials are essential for authenticating your API requests.

1. Log in to your Pinecone console.
2. Navigate to the "API Keys" section, typically found in your account settings or dashboard.
3. Locate your API Key (a unique alphanumeric string).
4. Note your Environment (e.g., us-west1-gcp), which specifies the cloud region where your Pinecone index is hosted.

Keep your API key secure and avoid exposing it in client-side code or public repositories. For production environments, consider using AWS Secrets Manager or similar secret management services to handle credentials securely.

Your first request

Once you have your API key and environment, you can make your first request. This example uses the Python client library, a commonly used SDK for Pinecone applications. The process involves installing the library, initializing Pinecone, creating an index, and then upserting vector data.

1. Install the Pinecone Python Client

Open your terminal or command prompt and install the Pinecone client:

pip install pinecone-client

2. Initialize Pinecone

Import the Pinecone class and initialize it with your API key and environment. Replace YOUR_API_KEY and YOUR_ENVIRONMENT with the values obtained from your console.

from pinecone import Pinecone, ServerlessSpec

api_key = "YOUR_API_KEY"
environment = "YOUR_ENVIRONMENT"

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

3. Create an Index

An index is where your vector data is stored and queried. For the free tier, you can create one index. Specify a name, dimension, and metric type (e.g., cosine for similarity calculations). The ServerlessSpec is a common configuration for new indices.

index_name = "my-first-index"

# Check if the index already exists
if index_name not in pinecone.list_indexes():
    pinecone.create_index(
        name=index_name,
        dimension=1536,  # Example dimension, depends on your embedding model
        metric='cosine', # Example metric, common for similarity search
        spec=ServerlessSpec(cloud='aws', region='us-west-2')
    )

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

The dimension (e.g., 1536) should match the output dimension of your chosen embedding model. For instance, OpenAI's text-embedding-ada-002 model produces embeddings of 1536 dimensions.

4. Upsert (Insert) Data

Upserting refers to inserting new vectors or updating existing ones. Each vector requires a unique ID, the vector data itself (a list of floats), and optional metadata.

# Example vectors to upsert
vectors_to_upsert = [
    {"id": "vec1", "values": [0.1, 0.2, 0.3, ..., 0.1536], "metadata": {"genre": "science fiction"}},
    {"id": "vec2", "values": [0.4, 0.5, 0.6, ..., 0.1536], "metadata": {"genre": "fantasy"}}
]

# In a real application, replace '...' with actual 1536-dimensional float vectors
# For demonstration, we'll create simple dummy vectors
import random

def generate_dummy_vector(dim):
    return [random.random() for _ in range(dim)]

dummy_vectors = [
    {"id": f"vec{i}", "values": generate_dummy_vector(1536), "metadata": {"source": "example"}}
    for i in range(5)
]

# Upsert the vectors
index.upsert(vectors=dummy_vectors)

# Verify the count of vectors in the index
index_stats = index.describe_index_stats()
print(f"Index stats: {index_stats}")

After running this code, your Pinecone index will contain the upserted vectors. The describe_index_stats() method is useful for confirming that data has been successfully added.

Common next steps

Once you have successfully upserted your first vectors, you can explore more advanced features and integrate Pinecone into your applications.

• Querying your index: Perform similarity searches to find the most relevant vectors based on a query vector. This is fundamental for semantic search and recommendation systems. Refer to the Pinecone querying documentation for examples.
• Filtering with metadata: Utilize metadata to refine your queries, allowing you to search within specific categories or conditions. The metadata filtering guide provides detailed instructions.
• Integrating with embedding models: Connect Pinecone with popular embedding models (e.g., from OpenAI, Hugging Face, or Cohere) to convert text or other data into vector representations before upserting them.
• Batch operations: For larger datasets, learn how to perform batch upserts and queries efficiently to optimize performance and resource usage.
• Monitoring and scaling: Understand how to monitor your index's performance and scale it as your data volume and query load increase. Pinecone provides tools within its console for this purpose.
• Explore use cases: Review Pinecone's use case examples to see how the platform is applied in real-world scenarios, such as building chatbots, content recommendations, or anomaly detection systems.

Troubleshooting the first call

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

• Incorrect API Key or Environment: Double-check that your api_key and environment values exactly match those found in your Pinecone console. Typos or leading/trailing spaces can cause authentication failures.
• Index Not Found: If you receive an error indicating the index does not exist, verify that the index_name in your code matches an index you have created in the Pinecone console. Remember that index creation can take a few minutes to complete.
• Dimension Mismatch: The dimension specified during index creation must exactly match the dimension of the vectors you are upserting. If your embedding model outputs 768-dimensional vectors, your index must also be 768-dimensional.
• Rate Limiting: For free tier accounts or during periods of high load, you might encounter rate limiting errors. Pinecone's rate limits documentation provides details on quotas. Consider implementing retry logic with exponential backoff for production applications.
• Network Connectivity: Ensure your development environment has stable network access to the Pinecone API endpoints. Firewall rules or VPNs might interfere with connections.
• SDK Version: Ensure you are using a compatible and up-to-date version of the Pinecone client library. Older versions might have bugs or lack support for newer features. Check the official Pinecone client installation guide for the latest version.
• Missing Dependencies: If you're using Python, ensure all necessary dependencies are installed. While pinecone-client handles most, issues with underlying packages like requests or urllib3 could occur.
• Error Messages: Carefully read the full error message provided by the API or SDK. These messages often contain specific clues about what went wrong, such as `"Invalid API key"` or `"Index 'my-index' not found"`.
• Pinecone Status Page: Check the Pinecone system status page for any ongoing service disruptions or outages that might be affecting the API.