> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Projects

> Retrieve every project owned by your account, authenticated with your API key.

Return a list of all projects owned by the authenticated user, with the basic status of each. Use this to enumerate your projects from a server-side script, CI/CD pipeline, or monitoring job before fanning out to per-project endpoints.

## Typical workflow

<Steps>
  <Step title="Authenticate">
    Pass `userId` and `apikey` as query parameters. Both are required.
  </Step>

  <Step title="Request the list">
    Call `GET /projects/projects-status` to retrieve every project you own.
  </Step>

  <Step title="Use the IDs">
    Take each project's `_id` and pass it anywhere a `projectId` is required — for example, [Project User Stats](/resources/api-reference/project-user-stats).
  </Step>
</Steps>

## Prerequisites

| Requirement | Where to get it                                                                |
| ----------- | ------------------------------------------------------------------------------ |
| User ID     | [Finding your IDs](/resources/api-reference/finding-your-user-and-project-ids) |
| API Key     | [API authentication](/resources/api-reference/api-authentication)              |

<Warning>
  This is a `GET` request — the API key is passed as the `apikey` query parameter. Note the all-lowercase casing: it's `apikey`, not `apiKey`. Treat the URL as sensitive: prefer server-side calls and avoid logging it in plain text.
</Warning>

## Query parameters

<ParamField query="userId" type="string" required>
  The ID of the account whose projects you want to list. Results are scoped to projects owned by this account.
</ParamField>

<ParamField query="apikey" type="string" required>
  Your Streampixel API key. Must match the key issued to `userId`.
</ParamField>

## Response

<ResponseField name="totalProjects" type="number">
  The number of projects returned.
</ResponseField>

<ResponseField name="projects" type="array">
  Array of project objects. Each item contains:

  <Expandable title="Project fields">
    <ResponseField name="_id" type="string">
      Unique project identifier. Use this anywhere a `projectId` is required.
    </ResponseField>

    <ResponseField name="name" type="string">
      Display name of the project.
    </ResponseField>

    <ResponseField name="status" type="boolean">
      Whether the project is currently active.
    </ResponseField>

    <ResponseField name="subscriptionStatus" type="string">
      The project's current subscription status.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -G https://api.streampixel.io/pixelStripeApi/projects/projects-status \
    --data-urlencode "userId=[YOUR_USER_ID]" \
    --data-urlencode "apikey=[YOUR_API_KEY]"
  ```

  ```javascript Node.js theme={"dark"}
  const axios = require('axios');

  const { data } = await axios.get(
    'https://api.streampixel.io/pixelStripeApi/projects/projects-status',
    {
      params: {
        userId: '[YOUR_USER_ID]',
        apikey: '[YOUR_API_KEY]',
      },
    }
  );

  console.log(`${data.totalProjects} projects:`, data.projects);
  ```

  ```python Python theme={"dark"}
  import requests

  response = requests.get(
      "https://api.streampixel.io/pixelStripeApi/projects/projects-status",
      params={
          "userId": "[YOUR_USER_ID]",
          "apikey": "[YOUR_API_KEY]",
      },
  )

  print("Projects:", response.json()["projects"])
  ```

  ```go Go theme={"dark"}
  package main

  import (
    "fmt"
    "io"
    "net/http"
    "net/url"
  )

  func main() {
    base := "https://api.streampixel.io/pixelStripeApi/projects/projects-status"
    q := url.Values{}
    q.Set("userId", "[YOUR_USER_ID]")
    q.Set("apikey", "[YOUR_API_KEY]")

    resp, err := http.Get(base + "?" + q.Encode())
    if err != nil {
      fmt.Println("Request failed:", err)
      return
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println("Response:", string(body))
  }
  ```

  ```java Java theme={"dark"}
  import okhttp3.*;

  public class ListProjects {
      public static void main(String[] args) throws Exception {
          OkHttpClient client = new OkHttpClient();

          HttpUrl url = HttpUrl.parse("https://api.streampixel.io/pixelStripeApi/projects/projects-status")
              .newBuilder()
              .addQueryParameter("userId", "[YOUR_USER_ID]")
              .addQueryParameter("apikey", "[YOUR_API_KEY]")
              .build();

          Request request = new Request.Builder().url(url).get().build();

          Response response = client.newCall(request).execute();
          System.out.println(response.body().string());
      }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {
    "totalProjects": 2,
    "projects": [
      {
        "_id": "664f1a2b3c4d5e6f7a8b9c0d",
        "name": "Showroom Demo",
        "status": true,
        "subscriptionStatus": "active"
      },
      {
        "_id": "664f1a2b3c4d5e6f7a8b9c0e",
        "name": "Configurator EU",
        "status": false,
        "subscriptionStatus": "active"
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={"dark"}
  {
    "message": "User ID is required"
  }
  ```

  ```json 401 Unauthorized theme={"dark"}
  {
    "message": "Invalid User"
  }
  ```

  ```json 401 Unauthorized theme={"dark"}
  {
    "message": "Unauthorized: Invalid API Key"
  }
  ```

  ```json 500 Internal Server Error theme={"dark"}
  {
    "message": "Internal server error"
  }
  ```
</ResponseExample>

## Error reference

| Status | Message                         | Cause                                                            |
| ------ | ------------------------------- | ---------------------------------------------------------------- |
| `400`  | `User ID is required`           | The `userId` query parameter was omitted.                        |
| `401`  | `Invalid User`                  | The supplied `userId` doesn't match any account.                 |
| `401`  | `Unauthorized: Invalid API Key` | The `apikey` is missing or doesn't match the user's current key. |
| `500`  | `Internal server error`         | Unexpected failure. Retry; if it persists, contact support.      |

<Tip>
  Cache the results for a few minutes if you call this repeatedly. Project membership rarely changes minute-to-minute, and avoiding redundant calls keeps you well under fair-use thresholds.
</Tip>

## Next

<CardGroup cols={2}>
  <Card title="Project User Stats" icon="users" href="/resources/api-reference/project-user-stats">
    Get live and queued user counts for a project.
  </Card>

  <Card title="Upload File API" icon="upload" href="/resources/api-reference/upload-file-api">
    Submit builds to a project via the API.
  </Card>
</CardGroup>