API Key Concepts

Fresh

GraphQL Overview

The IMDb API uses GraphQL — a query language that lets you specify exactly which fields you want in a response. Unlike REST APIs that return fixed data structures, GraphQL allows the client to declare the shape of the response. This means:

• No over-fetching: you only receive the fields you ask for
• No under-fetching: you can get nested related data in a single request
• Self-documenting: the schema describes what is available and what types each field returns
• Multiple queries in one: you can alias queries to retrieve multiple titles or names in a single request

All IMDb API requests are HTTP POST requests with a JSON body containing a query string (and optionally variables).

---

Pagination

The IMDb GraphQL API uses cursor-based pagination following the GraphQL Cursor Connections Specification. This is the standard approach for paginating through large lists of results.

How Cursor Pagination Works

Results are returned inside an edges array. Each edge contains a node (the actual item) and a cursor (a string that identifies the position of that item in the result set). The pageInfo object tells you whether more results are available and provides the cursor for the next page.

Key Fields

Field	Location	Description
edges	Connection object	Array of result items
node	Inside each edge	The actual data item
cursor	Inside each edge	Position identifier for this item
pageInfo	Connection object	Pagination metadata
endCursor	Inside pageInfo	Cursor value to pass for next page
hasNextPage	Inside pageInfo	true if more results exist

Pagination Example

{
  title(id: "tt0068646") {
    credits(first: 10, after: "CURSOR_VALUE") {
      edges {
        node {
          name {
            id
            nameText { text }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Pass the endCursor value as the after argument in your next request to fetch the following page. Continue until hasNextPage is false.

---

Endpoint

All GraphQL queries are sent as HTTP POST requests to:

http://api-fulfill.dataexchange.us-east-1.amazonaws.com/v1

The endpoint does not change between queries. The GraphQL query itself determines what data is returned.

---

Required Headers

Every request must include these HTTP headers:

Header	Value
Content-Type	application/graphql
x-api-key	Your API key from the Data Exchange subscription
x-amzn-dataexchange-data-set-id	Your data set ID
revision-id	Your revision ID
asset-id	Your asset ID

The x-api-key header authenticates your request at the application level. AWS Signature Version 4 (SigV4) authentication operates at the transport level and is handled by your AWS SDK or manual signing implementation.

---

AWS Authentication

The API requires AWS Signature Version 4 authentication in addition to the API key. There are two ways to provide your AWS credentials.

Using Profiles (Recommended for Development)

AWS profiles allow you to store credentials locally and reference them by name.

Configure a profile:

aws configure --profile imdb-api

You will be prompted for:

• AWS Access Key ID
• AWS Secret Access Key
• Default region: us-east-1
• Default output format: json

Use the profile in your environment:

On Linux or macOS:

export AWS_PROFILE=imdb-api

On Windows (Command Prompt):

setx AWS_PROFILE imdb-api

On Windows (PowerShell):

$env:AWS_PROFILE = "imdb-api"

Once set, AWS SDKs automatically use the credentials from the named profile.

Without Profiles (Environment Variables)

For server environments, CI/CD, and containerized deployments, pass credentials directly as environment variables:

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-east-1

On Windows:

setx AWS_ACCESS_KEY_ID AKIAIOSFODNN7EXAMPLE
setx AWS_SECRET_ACCESS_KEY wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
setx AWS_DEFAULT_REGION us-east-1

Service Name for Signing

When signing requests manually, use dataexchange as the AWS service name. The region is us-east-1.

---

Viewing API Usage and Cost

To monitor your API usage and associated costs:

1. Open the AWS Management Console
2. Navigate to AWS Cost Explorer (search "Cost Explorer" in the service search)
3. If not already enabled, click Enable Cost Explorer — it takes up to 24 hours to start showing data
4. Use Filter by Service and select AWS Data Exchange to see IMDb API costs
5. Set the time range and group by API to see per-endpoint usage

AWS Data Exchange charges are based on the number of API calls made. Cost Explorer shows both call counts and associated dollar amounts to help you manage your usage.